@jsleekr/graft 5.7.0

package/dist/parser/parser.js

@@ -0,0 +1,1175 @@
+// src/parser/parser.ts
+import { TokenType, KEYWORDS } from '../lexer/tokens.js';
+import { Lexer } from '../lexer/lexer.js';
+import { GraftError } from '../errors/diagnostics.js';
+import { BUILTIN_FUNCTIONS, } from './ast.js';
+// Build a Set of all keyword token types for O(1) lookup.
+// Used by expectIdentifierOrKeyword() to accept keywords as contextual identifiers.
+const KEYWORD_TYPES = new Set(Object.values(KEYWORDS));
+export class Parser {
+    tokens;
+    pos = 0;
+    errors = [];
+    static MAX_ERRORS = 25;
+    static DECLARATION_KEYWORDS = new Set([
+        TokenType.Context, TokenType.Node, TokenType.Memory,
+        TokenType.Graph, TokenType.Edge, TokenType.Import,
+    ]);
+    constructor(tokens) {
+        this.tokens = tokens;
+    }
+    parse() {
+        const program = {
+            imports: [],
+            memories: [],
+            contexts: [],
+            nodes: [],
+            edges: [],
+            graphs: [],
+        };
+        let seenNonImport = false;
+        while (!this.isAtEnd()) {
+            if (this.errors.length >= Parser.MAX_ERRORS)
+                break;
+            const token = this.current();
+            try {
+                switch (token.type) {
+                    case TokenType.Import:
+                        if (seenNonImport) {
+                            this.errors.push(this.error('Import declarations must appear before all other declarations'));
+                            this.advance(); // advance past the Import keyword
+                            this.synchronize();
+                            break;
+                        }
+                        program.imports.push(this.parseImportDecl());
+                        break;
+                    case TokenType.Memory:
+                        seenNonImport = true;
+                        program.memories.push(this.parseMemoryDecl());
+                        break;
+                    case TokenType.Context:
+                        seenNonImport = true;
+                        program.contexts.push(this.parseContext());
+                        break;
+                    case TokenType.Node:
+                        seenNonImport = true;
+                        program.nodes.push(this.parseNode());
+                        break;
+                    case TokenType.Edge:
+                        seenNonImport = true;
+                        program.edges.push(this.parseEdge());
+                        break;
+                    case TokenType.Graph:
+                        seenNonImport = true;
+                        program.graphs.push(this.parseGraph());
+                        break;
+                    default: {
+                        this.errors.push(this.error(`Unexpected token '${token.value}', expected 'import', 'memory', 'context', 'node', 'edge', or 'graph'`));
+                        const posBefore = this.pos;
+                        this.synchronize();
+                        if (this.pos === posBefore && !this.isAtEnd())
+                            this.advance();
+                        break;
+                    }
+                }
+            }
+            catch (e) {
+                if (e instanceof GraftError) {
+                    this.errors.push(e);
+                    const posBefore = this.pos;
+                    this.synchronize();
+                    if (this.pos === posBefore && !this.isAtEnd())
+                        this.advance();
+                }
+                else {
+                    throw e;
+                }
+            }
+        }
+        return { program, errors: this.errors };
+    }
+    synchronize() {
+        let braceDepth = 0;
+        while (!this.isAtEnd()) {
+            const token = this.current();
+            if (token.type === TokenType.LBrace) {
+                braceDepth++;
+            }
+            else if (token.type === TokenType.RBrace) {
+                if (braceDepth > 0) {
+                    braceDepth--;
+                }
+                else {
+                    // Closing brace at depth 0 — skip it and stop
+                    this.advance();
+                    break;
+                }
+            }
+            else if (braceDepth === 0 && Parser.DECLARATION_KEYWORDS.has(token.type)) {
+                // At top level, found a declaration keyword — stop (don't consume it)
+                break;
+            }
+            this.advance();
+        }
+    }
+    // --- Import ------------------------------------------------
+    parseImportDecl() {
+        const loc = this.current().location;
+        this.expect(TokenType.Import);
+        this.expect(TokenType.LBrace);
+        const names = [];
+        while (!this.check(TokenType.RBrace)) {
+            if (names.length > 0)
+                this.expect(TokenType.Comma);
+            names.push(this.expectIdentifier());
+        }
+        if (names.length === 0) {
+            throw this.error('Import must specify at least one name');
+        }
+        this.expect(TokenType.RBrace);
+        this.expect(TokenType.From);
+        const pathToken = this.expect(TokenType.StringLiteral);
+        const path = pathToken.value;
+        if (path === '') {
+            throw this.error('Import path cannot be empty');
+        }
+        return { names, path, location: loc };
+    }
+    // --- Memory ------------------------------------------------
+    parseMemoryDecl() {
+        const loc = this.current().location;
+        this.expect(TokenType.Memory);
+        const name = this.expectIdentifier();
+        this.expect(TokenType.LParen);
+        this.expect(TokenType.MaxTokens);
+        this.expect(TokenType.Colon);
+        const maxTokens = this.parseTokenValue();
+        let storage = 'file';
+        if (this.check(TokenType.Comma)) {
+            this.advance();
+            this.expect(TokenType.Storage);
+            this.expect(TokenType.Colon);
+            const storageValue = this.expectIdentifierOrKeyword();
+            if (storageValue !== 'file') {
+                throw this.error(`Unknown storage type '${storageValue}', expected 'file'`);
+            }
+            storage = 'file';
+        }
+        this.expect(TokenType.RParen);
+        this.expect(TokenType.LBrace);
+        const fields = this.parseFields();
+        this.expect(TokenType.RBrace);
+        return { name, maxTokens, storage, fields, location: loc };
+    }
+    // --- Context ------------------------------------------------
+    parseContext() {
+        const loc = this.current().location;
+        this.expect(TokenType.Context);
+        const name = this.expectIdentifier();
+        // Parameters: (max_tokens: <Int>)
+        this.expect(TokenType.LParen);
+        this.expect(TokenType.MaxTokens);
+        this.expect(TokenType.Colon);
+        const maxTokens = this.parseTokenValue();
+        this.expect(TokenType.RParen);
+        // Body: { fields }
+        this.expect(TokenType.LBrace);
+        const fields = this.parseFields();
+        this.expect(TokenType.RBrace);
+        return { name, maxTokens, fields, location: loc };
+    }
+    // --- Node ---------------------------------------------------
+    parseNode() {
+        const loc = this.current().location;
+        this.expect(TokenType.Node);
+        const name = this.expectIdentifier();
+        // Parameters: (model: <id>, budget: <in>/<out>)
+        this.expect(TokenType.LParen);
+        this.expect(TokenType.Model);
+        this.expect(TokenType.Colon);
+        const model = this.expectIdentifier();
+        this.expect(TokenType.Comma);
+        this.expect(TokenType.Budget);
+        this.expect(TokenType.Colon);
+        const budgetIn = this.parseTokenValue();
+        this.expect(TokenType.Slash);
+        const budgetOut = this.parseTokenValue();
+        this.expect(TokenType.RParen);
+        // Body
+        this.expect(TokenType.LBrace);
+        let reads = [];
+        let tools = [];
+        let writes = [];
+        let onFailure;
+        let produces;
+        let hasWrites = false;
+        while (!this.check(TokenType.RBrace)) {
+            if (this.check(TokenType.Reads)) {
+                this.advance();
+                this.expect(TokenType.Colon);
+                reads = this.parseContextRefList();
+            }
+            else if (this.check(TokenType.Tools)) {
+                this.advance();
+                this.expect(TokenType.Colon);
+                tools = this.parseIdentifierList();
+            }
+            else if (this.check(TokenType.Writes)) {
+                if (hasWrites) {
+                    throw this.error('Duplicate writes clause in node');
+                }
+                hasWrites = true;
+                this.advance();
+                this.expect(TokenType.Colon);
+                writes = this.parseWriteRefList();
+            }
+            else if (this.check(TokenType.OnFailure)) {
+                this.advance();
+                this.expect(TokenType.Colon);
+                onFailure = this.parseFailureStrategy();
+            }
+            else if (this.check(TokenType.Produces)) {
+                produces = this.parseProduces();
+            }
+            else {
+                throw this.error(`Unexpected token '${this.current().value}' in node body`);
+            }
+        }
+        this.expect(TokenType.RBrace);
+        if (!produces) {
+            throw new GraftError('Node must have a produces declaration', loc, 'error', 'PARSE_MISSING_FIELD');
+        }
+        return { name, model, budgetIn, budgetOut, reads, tools, writes, onFailure, produces, location: loc };
+    }
+    parseProduces() {
+        const loc = this.current().location;
+        this.expect(TokenType.Produces);
+        const name = this.expectIdentifier();
+        this.expect(TokenType.LBrace);
+        const fields = this.parseFields();
+        this.expect(TokenType.RBrace);
+        return { name, fields, location: loc };
+    }
+    parseContextRefList() {
+        this.expect(TokenType.LBracket);
+        const refs = [];
+        while (!this.check(TokenType.RBracket)) {
+            if (refs.length > 0)
+                this.expect(TokenType.Comma);
+            const loc = this.current().location;
+            const context = this.expectIdentifier();
+            let field;
+            if (this.check(TokenType.Dot)) {
+                this.advance();
+                if (this.check(TokenType.LBrace)) {
+                    this.advance();
+                    const fields = [];
+                    while (!this.check(TokenType.RBrace)) {
+                        if (fields.length > 0)
+                            this.expect(TokenType.Comma);
+                        fields.push(this.expectIdentifierOrKeyword());
+                    }
+                    if (fields.length === 0) {
+                        throw this.error('Multi-field read must specify at least one field');
+                    }
+                    this.expect(TokenType.RBrace);
+                    field = fields;
+                }
+                else {
+                    field = [this.expectIdentifierOrKeyword()];
+                }
+            }
+            refs.push({ context, field, location: loc });
+        }
+        this.expect(TokenType.RBracket);
+        return refs;
+    }
+    parseWriteRefList() {
+        this.expect(TokenType.LBracket);
+        const refs = [];
+        while (!this.check(TokenType.RBracket)) {
+            if (refs.length > 0)
+                this.expect(TokenType.Comma);
+            const loc = this.current().location;
+            const memory = this.expectIdentifier();
+            let field;
+            if (this.check(TokenType.Dot)) {
+                this.advance();
+                field = this.expectIdentifierOrKeyword();
+            }
+            refs.push({ memory, field, location: loc });
+        }
+        this.expect(TokenType.RBracket);
+        return refs;
+    }
+    parseIdentifierList() {
+        this.expect(TokenType.LBracket);
+        const ids = [];
+        while (!this.check(TokenType.RBracket)) {
+            if (ids.length > 0)
+                this.expect(TokenType.Comma);
+            ids.push(this.expectIdentifierOrKeyword());
+        }
+        this.expect(TokenType.RBracket);
+        return ids;
+    }
+    parseFailureStrategy() {
+        if (this.check(TokenType.Retry)) {
+            this.advance();
+            this.expect(TokenType.LParen);
+            const max = this.parseIntValue();
+            // Check for: retry(2, fallback(NodeName))
+            if (this.check(TokenType.Comma)) {
+                this.advance();
+                this.expect(TokenType.Fallback);
+                this.expect(TokenType.LParen);
+                const node = this.expectIdentifier();
+                this.expect(TokenType.RParen);
+                this.expect(TokenType.RParen);
+                return { type: 'retry_then_fallback', max, node };
+            }
+            this.expect(TokenType.RParen);
+            return { type: 'retry', max };
+        }
+        if (this.check(TokenType.Fallback)) {
+            this.advance();
+            this.expect(TokenType.LParen);
+            const node = this.expectIdentifier();
+            this.expect(TokenType.RParen);
+            return { type: 'fallback', node };
+        }
+        if (this.check(TokenType.Skip)) {
+            this.advance();
+            return { type: 'skip' };
+        }
+        if (this.check(TokenType.Abort)) {
+            this.advance();
+            return { type: 'abort' };
+        }
+        throw this.error('Expected failure strategy (retry, fallback, skip, abort)');
+    }
+    // --- Edge ---------------------------------------------------
+    parseEdge() {
+        const loc = this.current().location;
+        this.expect(TokenType.Edge);
+        const source = this.expectIdentifier();
+        this.expect(TokenType.Arrow);
+        let target;
+        let transforms = [];
+        if (this.check(TokenType.LBrace)) {
+            // Conditional routing
+            target = this.parseConditionalTarget();
+        }
+        else {
+            // Direct target
+            const node = this.expectIdentifier();
+            target = { kind: 'direct', node };
+            // Parse pipe transforms
+            while (this.check(TokenType.Pipe)) {
+                this.advance();
+                transforms.push(this.parseTransform());
+            }
+        }
+        return { source, target, transforms, location: loc };
+    }
+    parseConditionalTarget() {
+        this.expect(TokenType.LBrace);
+        const branches = [];
+        while (!this.check(TokenType.RBrace)) {
+            if (this.check(TokenType.When)) {
+                this.advance();
+                const condition = this.parseCondition();
+                this.expect(TokenType.Arrow);
+                const target = this.check(TokenType.Done) ? (this.advance(), 'done') : this.expectIdentifier();
+                branches.push({ condition, target });
+            }
+            else if (this.check(TokenType.Else)) {
+                this.advance();
+                this.expect(TokenType.Arrow);
+                const target = this.check(TokenType.Done) ? (this.advance(), 'done') : this.expectIdentifier();
+                branches.push({ condition: undefined, target });
+            }
+            else {
+                throw this.error(`Expected 'when' or 'else' in conditional edge`);
+            }
+        }
+        this.expect(TokenType.RBrace);
+        return { kind: 'conditional', branches };
+    }
+    parseTransform() {
+        if (this.check(TokenType.Select)) {
+            this.advance();
+            this.expect(TokenType.LParen);
+            const fields = [];
+            fields.push(this.expectIdentifierOrKeyword());
+            while (this.check(TokenType.Comma)) {
+                this.advance();
+                fields.push(this.expectIdentifierOrKeyword());
+            }
+            this.expect(TokenType.RParen);
+            return { type: 'select', fields };
+        }
+        if (this.check(TokenType.Filter)) {
+            this.advance();
+            this.expect(TokenType.LParen);
+            const field = this.expectIdentifierOrKeyword();
+            this.expect(TokenType.Comma);
+            const condition = this.parseCondition();
+            this.expect(TokenType.RParen);
+            return { type: 'filter', field, condition };
+        }
+        if (this.check(TokenType.Drop)) {
+            this.advance();
+            this.expect(TokenType.LParen);
+            const field = this.expectIdentifierOrKeyword();
+            this.expect(TokenType.RParen);
+            return { type: 'drop', field };
+        }
+        if (this.check(TokenType.Compact)) {
+            this.advance();
+            return { type: 'compact' };
+        }
+        if (this.check(TokenType.Truncate)) {
+            this.advance();
+            this.expect(TokenType.LParen);
+            const tokens = this.parseTokenValue();
+            this.expect(TokenType.RParen);
+            return { type: 'truncate', tokens };
+        }
+        throw this.error('Expected transform operation (select, filter, drop, compact, truncate)');
+    }
+    parseCondition() {
+        const loc = this.current().location;
+        const field = this.expectIdentifierOrKeyword();
+        const left = { kind: 'field_access', segments: [field], location: loc };
+        const opToken = this.current();
+        let op;
+        switch (opToken.type) {
+            case TokenType.GreaterEqual:
+                op = '>=';
+                break;
+            case TokenType.Greater:
+                op = '>';
+                break;
+            case TokenType.LessEqual:
+                op = '<=';
+                break;
+            case TokenType.Less:
+                op = '<';
+                break;
+            case TokenType.EqualEqual:
+                op = '==';
+                break;
+            case TokenType.BangEqual:
+                op = '!=';
+                break;
+            default:
+                throw this.error(`Expected comparison operator, got '${opToken.value}'`);
+        }
+        this.advance();
+        const value = this.parseConditionValue();
+        const right = { kind: 'literal', value, location: this.tokens[this.pos - 1].location };
+        return { kind: 'binary', op, left, right, location: loc };
+    }
+    parseConditionValue() {
+        const token = this.current();
+        if (token.type === TokenType.IntegerLiteral) {
+            this.advance();
+            return parseInt(token.value, 10);
+        }
+        if (token.type === TokenType.KIntegerLiteral) {
+            this.advance();
+            // parseInt("5k", 10) returns 5 per the JS spec: parseInt stops at first non-digit.
+            return parseInt(token.value, 10) * 1000;
+        }
+        if (token.type === TokenType.FloatLiteral) {
+            this.advance();
+            return parseFloat(token.value);
+        }
+        if (token.type === TokenType.StringLiteral) {
+            this.advance();
+            return token.value;
+        }
+        if (token.type === TokenType.True) {
+            this.advance();
+            return true;
+        }
+        if (token.type === TokenType.False) {
+            this.advance();
+            return false;
+        }
+        // Allow bare identifiers as string values (e.g., severity >= medium)
+        if (token.type === TokenType.Identifier || KEYWORD_TYPES.has(token.type)) {
+            this.advance();
+            return token.value;
+        }
+        throw this.error(`Expected value in condition, got '${token.value}'`);
+    }
+    // --- Graph --------------------------------------------------
+    parseGraph() {
+        const loc = this.current().location;
+        this.expect(TokenType.Graph);
+        const name = this.expectIdentifier();
+        // Parameters: (input: X, output: Y, budget: Nk [, param: Type]*)
+        this.expect(TokenType.LParen);
+        this.expect(TokenType.Input);
+        this.expect(TokenType.Colon);
+        const input = this.expectIdentifier();
+        this.expect(TokenType.Comma);
+        this.expect(TokenType.Output);
+        this.expect(TokenType.Colon);
+        const output = this.expectIdentifier();
+        this.expect(TokenType.Comma);
+        this.expect(TokenType.Budget);
+        this.expect(TokenType.Colon);
+        const budget = this.parseTokenValue();
+        // Optional params after budget
+        const params = [];
+        while (this.check(TokenType.Comma)) {
+            this.advance(); // consume comma
+            if (this.check(TokenType.RParen))
+                break; // trailing comma
+            params.push(this.parseGraphParam());
+        }
+        this.expect(TokenType.RParen);
+        // Body: { FlowNodes -> done }
+        this.expect(TokenType.LBrace);
+        const flow = this.parseFlowNodes(/* insideBlock */ false);
+        this.expect(TokenType.RBrace);
+        return { name, input, output, budget, params, flow, location: loc };
+    }
+    parseGraphParam() {
+        const loc = this.current().location;
+        const name = this.expectIdentifierOrKeyword();
+        this.expect(TokenType.Colon);
+        // Type: Node (identifier), Int, String, Bool (keywords)
+        const typeToken = this.current();
+        let type;
+        if (typeToken.type === TokenType.Identifier && typeToken.value === 'Node') {
+            type = 'Node';
+            this.advance();
+        }
+        else if (typeToken.type === TokenType.Int) {
+            type = 'Int';
+            this.advance();
+        }
+        else if (typeToken.type === TokenType.String) {
+            type = 'String';
+            this.advance();
+        }
+        else if (typeToken.type === TokenType.Bool) {
+            type = 'Bool';
+            this.advance();
+        }
+        else {
+            throw this.error(`Expected param type (Node, Int, String, Bool), got '${typeToken.value}'`);
+        }
+        // Optional default value
+        let defaultVal;
+        if (this.check(TokenType.Equals)) {
+            this.advance();
+            defaultVal = this.parseConditionValue();
+        }
+        return { name, type, default: defaultVal, location: loc };
+    }
+    /**
+     * Parse a sequence of flow nodes separated by arrows.
+     * When insideBlock=true, stops when no more arrows (next token should be RBrace).
+     * When insideBlock=false, expects -> done to terminate.
+     */
+    parseFlowNodes(insideBlock) {
+        const steps = [];
+        // Parse first step
+        steps.push(this.parseFlowNode());
+        while (this.check(TokenType.Arrow)) {
+            this.advance(); // consume ->
+            // Check for 'done'
+            if (this.check(TokenType.Done)) {
+                this.advance();
+                if (insideBlock) {
+                    throw this.error("'done' is not allowed inside a foreach or parallel block");
+                }
+                return steps;
+            }
+            // Check for RBrace -- end of foreach body after arrow would be an error
+            if (this.check(TokenType.RBrace)) {
+                throw this.error("Expected flow step after '->'");
+            }
+            steps.push(this.parseFlowNode());
+        }
+        // If we get here without 'done' at top level, that's an error
+        if (!insideBlock) {
+            throw this.error("Expected '-> done' to terminate graph flow");
+        }
+        // insideBlock: we stop when no more arrows (next token should be RBrace)
+        return steps;
+    }
+    /**
+     * Parse a single flow node: identifier, parallel block, foreach block,
+     * let binding, or graph call.
+     */
+    parseFlowNode() {
+        if (this.check(TokenType.Parallel)) {
+            return this.parseParallelStep();
+        }
+        if (this.check(TokenType.Foreach)) {
+            return this.parseForeachStep();
+        }
+        if (this.check(TokenType.Let)) {
+            return this.parseLetStep();
+        }
+        // Identifier: could be a node reference or a graph call
+        // Disambiguate: Identifier followed by LParen is a graph call
+        const loc = this.current().location;
+        const name = this.expectIdentifier();
+        if (this.check(TokenType.LParen)) {
+            return this.parseGraphCall(name, loc);
+        }
+        return { kind: 'node', name, location: loc };
+    }
+    parseLetStep() {
+        const loc = this.current().location;
+        this.expect(TokenType.Let);
+        const name = this.expectIdentifierOrKeyword();
+        this.expect(TokenType.Equals);
+        const value = this.parseExpr();
+        return { kind: 'let', name, value, location: loc };
+    }
+    parseGraphCall(name, location) {
+        this.expect(TokenType.LParen);
+        const args = [];
+        while (!this.check(TokenType.RParen)) {
+            if (args.length > 0)
+                this.expect(TokenType.Comma);
+            const argLoc = this.current().location;
+            const argName = this.expectIdentifierOrKeyword();
+            this.expect(TokenType.Colon);
+            const value = this.parseExpr();
+            args.push({ name: argName, value, location: argLoc });
+        }
+        this.expect(TokenType.RParen);
+        return { kind: 'graph_call', name, args, location };
+    }
+    /**
+     * parallel { SecurityReviewer  PerformanceReviewer  StyleReviewer }
+     *
+     * Branches are whitespace-separated identifiers (no commas required).
+     * Optional commas are accepted for user convenience.
+     */
+    parseParallelStep() {
+        const loc = this.current().location;
+        this.expect(TokenType.Parallel);
+        this.expect(TokenType.LBrace);
+        const branches = [];
+        while (!this.check(TokenType.RBrace)) {
+            if (branches.length > 0 && this.check(TokenType.Comma)) {
+                this.advance(); // optional comma
+            }
+            branches.push(this.expectIdentifier());
+        }
+        this.expect(TokenType.RBrace);
+        if (branches.length < 2) {
+            throw this.error('parallel block must contain at least 2 branches');
+        }
+        return { kind: 'parallel', branches, location: loc };
+    }
+    /**
+     * foreach(Planner.output.steps as step, max_iterations: 5) {
+     *   Implementer -> Verifier
+     * }
+     */
+    parseForeachStep() {
+        const loc = this.current().location;
+        this.expect(TokenType.Foreach);
+        this.expect(TokenType.LParen);
+        // Source: Planner.output.steps
+        const source = this.expectIdentifier(); // "Planner"
+        this.expect(TokenType.Dot);
+        this.expect(TokenType.Output); // "output" keyword token
+        this.expect(TokenType.Dot);
+        const field = this.expectIdentifierOrKeyword(); // "steps"
+        // Binding: as step
+        this.expect(TokenType.As);
+        const binding = this.expectIdentifierOrKeyword(); // "step"
+        // max_iterations: 5
+        this.expect(TokenType.Comma);
+        this.expect(TokenType.MaxIterations);
+        this.expect(TokenType.Colon);
+        const maxIterations = this.parseIntValue();
+        if (maxIterations < 1) {
+            throw this.error('max_iterations must be at least 1');
+        }
+        this.expect(TokenType.RParen);
+        // Body: { Implementer -> Verifier }
+        this.expect(TokenType.LBrace);
+        const body = this.parseFlowNodes(/* insideBlock */ true);
+        this.expect(TokenType.RBrace);
+        if (body.length === 0) {
+            throw this.error('foreach body must contain at least one step');
+        }
+        // v1.1+: enforce no nesting (body must contain only 'node', 'let', or 'graph_call' entries)
+        for (const step of body) {
+            if (step.kind === 'parallel' || step.kind === 'foreach') {
+                throw this.error('Nested parallel or foreach inside foreach is not supported');
+            }
+        }
+        return { kind: 'foreach', source, field, binding, maxIterations, body, location: loc };
+    }
+    // --- Expressions --------------------------------------------
+    parseExpr() {
+        return this.parseNullCoalesce();
+    }
+    parseNullCoalesce() {
+        let left = this.parseLogicalOr();
+        while (this.check(TokenType.QuestionQuestion)) {
+            this.advance();
+            const right = this.parseLogicalOr();
+            left = { kind: 'binary', op: '??', left, right, location: left.location };
+        }
+        return left;
+    }
+    parseLogicalOr() {
+        let left = this.parseLogicalAnd();
+        while (this.check(TokenType.PipePipe)) {
+            this.advance();
+            const right = this.parseLogicalAnd();
+            left = { kind: 'binary', op: '||', left, right, location: left.location };
+        }
+        return left;
+    }
+    parseLogicalAnd() {
+        let left = this.parseComparison();
+        while (this.check(TokenType.AmpAmp)) {
+            this.advance();
+            const right = this.parseComparison();
+            left = { kind: 'binary', op: '&&', left, right, location: left.location };
+        }
+        return left;
+    }
+    parseComparison() {
+        let left = this.parseAdditive();
+        while (this.check(TokenType.Greater) || this.check(TokenType.Less) ||
+            this.check(TokenType.GreaterEqual) || this.check(TokenType.LessEqual) ||
+            this.check(TokenType.EqualEqual) || this.check(TokenType.BangEqual)) {
+            const opToken = this.current();
+            let op;
+            switch (opToken.type) {
+                case TokenType.Greater:
+                    op = '>';
+                    break;
+                case TokenType.Less:
+                    op = '<';
+                    break;
+                case TokenType.GreaterEqual:
+                    op = '>=';
+                    break;
+                case TokenType.LessEqual:
+                    op = '<=';
+                    break;
+                case TokenType.EqualEqual:
+                    op = '==';
+                    break;
+                case TokenType.BangEqual:
+                    op = '!=';
+                    break;
+                default: throw this.error(`Unexpected operator '${opToken.value}'`);
+            }
+            this.advance();
+            const right = this.parseAdditive();
+            left = { kind: 'binary', op, left, right, location: left.location };
+        }
+        return left;
+    }
+    parseAdditive() {
+        let left = this.parseMultiplicative();
+        while (this.check(TokenType.Plus) || this.check(TokenType.Minus)) {
+            const opToken = this.current();
+            const op = opToken.type === TokenType.Plus ? '+' : '-';
+            this.advance();
+            const right = this.parseMultiplicative();
+            left = { kind: 'binary', op, left, right, location: left.location };
+        }
+        return left;
+    }
+    parseMultiplicative() {
+        let left = this.parseUnary();
+        while (this.check(TokenType.Star) || this.check(TokenType.Percent) || this.check(TokenType.Slash)) {
+            const opToken = this.current();
+            let op;
+            switch (opToken.type) {
+                case TokenType.Star:
+                    op = '*';
+                    break;
+                case TokenType.Percent:
+                    op = '%';
+                    break;
+                case TokenType.Slash:
+                    op = '/';
+                    break;
+                default: throw this.error(`Unexpected operator '${opToken.value}'`);
+            }
+            this.advance();
+            const right = this.parseUnary();
+            left = { kind: 'binary', op, left, right, location: left.location };
+        }
+        return left;
+    }
+    parseUnary() {
+        if (this.check(TokenType.Minus)) {
+            const loc = this.current().location;
+            this.advance();
+            const operand = this.parseUnary();
+            return { kind: 'unary', op: '-', operand, location: loc };
+        }
+        if (this.check(TokenType.Bang)) {
+            const loc = this.current().location;
+            this.advance();
+            const operand = this.parseUnary();
+            return { kind: 'unary', op: '!', operand, location: loc };
+        }
+        return this.parsePrimary();
+    }
+    parseTemplateParts(raw, loc) {
+        const parts = [];
+        let i = 0;
+        while (i < raw.length) {
+            const dollarIdx = raw.indexOf('${', i);
+            if (dollarIdx === -1) {
+                // Rest is plain text
+                if (i < raw.length) {
+                    parts.push({ kind: 'text', value: raw.slice(i) });
+                }
+                break;
+            }
+            // Text before ${
+            if (dollarIdx > i) {
+                parts.push({ kind: 'text', value: raw.slice(i, dollarIdx) });
+            }
+            // Find matching } by counting brace depth
+            let depth = 1;
+            let j = dollarIdx + 2;
+            while (j < raw.length && depth > 0) {
+                if (raw[j] === '{')
+                    depth++;
+                else if (raw[j] === '}')
+                    depth--;
+                if (depth > 0)
+                    j++;
+            }
+            if (depth !== 0) {
+                throw new GraftError('Unterminated template interpolation', loc);
+            }
+            // Parse the expression inside ${ ... }
+            const exprSource = raw.slice(dollarIdx + 2, j);
+            const innerLexer = new Lexer(exprSource);
+            const innerTokens = innerLexer.tokenize();
+            // Remove EOF token for parsing
+            const exprTokens = innerTokens.filter(t => t.type !== TokenType.EOF);
+            // Re-add EOF
+            exprTokens.push({ type: TokenType.EOF, value: '', location: loc });
+            const innerParser = new Parser(exprTokens);
+            const expr = innerParser.parseExpr();
+            parts.push({ kind: 'expr', value: expr });
+            i = j + 1; // skip past }
+        }
+        return parts;
+    }
+    parsePrimary() {
+        const token = this.current();
+        const loc = token.location;
+        // Integer literal
+        if (token.type === TokenType.IntegerLiteral) {
+            this.advance();
+            return { kind: 'literal', value: parseInt(token.value, 10), location: loc };
+        }
+        // K-integer literal
+        if (token.type === TokenType.KIntegerLiteral) {
+            this.advance();
+            return { kind: 'literal', value: parseInt(token.value, 10) * 1000, location: loc };
+        }
+        // Float literal
+        if (token.type === TokenType.FloatLiteral) {
+            this.advance();
+            return { kind: 'literal', value: parseFloat(token.value), location: loc };
+        }
+        // String literal
+        if (token.type === TokenType.StringLiteral) {
+            this.advance();
+            return { kind: 'literal', value: token.value, location: loc };
+        }
+        // Template string: "text ${expr} text"
+        if (token.type === TokenType.TemplateString) {
+            this.advance();
+            const parts = this.parseTemplateParts(token.value, loc);
+            return { kind: 'template', parts, location: loc };
+        }
+        // Boolean literals
+        if (token.type === TokenType.True) {
+            this.advance();
+            return { kind: 'literal', value: true, location: loc };
+        }
+        if (token.type === TokenType.False) {
+            this.advance();
+            return { kind: 'literal', value: false, location: loc };
+        }
+        // Grouped expression
+        if (token.type === TokenType.LParen) {
+            this.advance();
+            const inner = this.parseExpr();
+            this.expect(TokenType.RParen);
+            return { kind: 'group', inner, location: loc };
+        }
+        // Built-in function call: len(...), max(...), min(...), str(...)
+        if (token.type === TokenType.Identifier && token.value in BUILTIN_FUNCTIONS && this.peekType(1) === TokenType.LParen) {
+            const name = token.value;
+            this.advance(); // consume function name
+            this.advance(); // consume LParen
+            const args = [];
+            if (!this.check(TokenType.RParen)) {
+                args.push(this.parseExpr());
+                while (this.check(TokenType.Comma)) {
+                    this.advance();
+                    args.push(this.parseExpr());
+                }
+            }
+            this.expect(TokenType.RParen);
+            return { kind: 'call', name, args, location: loc };
+        }
+        // Conditional expression: if <expr> then <expr> else <expr>
+        if (token.type === TokenType.If) {
+            this.advance();
+            const condition = this.parseExpr();
+            this.expect(TokenType.Then);
+            const consequent = this.parseExpr();
+            this.expect(TokenType.Else);
+            const alternate = this.parseExpr();
+            return { kind: 'conditional', condition, consequent, alternate, location: loc };
+        }
+        // Field access: identifier (or keyword) followed by optional dots
+        if (token.type === TokenType.Identifier || KEYWORD_TYPES.has(token.type)) {
+            this.advance();
+            const segments = [token.value];
+            while (this.check(TokenType.Dot)) {
+                this.advance();
+                const seg = this.expectIdentifierOrKeyword();
+                segments.push(seg);
+            }
+            return { kind: 'field_access', segments, location: loc };
+        }
+        throw this.error(`Expected expression, got '${token.value}' (${token.type})`);
+    }
+    // --- Types --------------------------------------------------
+    parseType() {
+        const token = this.current();
+        // List<T>
+        if (token.type === TokenType.List) {
+            this.advance();
+            this.expect(TokenType.Less);
+            const element = this.parseTypeOrInlineStruct();
+            this.expect(TokenType.Greater);
+            return { kind: 'list', element };
+        }
+        // Map<K, V>
+        if (token.type === TokenType.Map) {
+            this.advance();
+            this.expect(TokenType.Less);
+            const key = this.parseType();
+            this.expect(TokenType.Comma);
+            const value = this.parseType();
+            this.expect(TokenType.Greater);
+            return { kind: 'map', key, value };
+        }
+        // Optional<T>
+        if (token.type === TokenType.Optional) {
+            this.advance();
+            this.expect(TokenType.Less);
+            const inner = this.parseTypeOrInlineStruct();
+            this.expect(TokenType.Greater);
+            return { kind: 'optional', inner };
+        }
+        // TokenBounded<T, max>
+        if (token.type === TokenType.TokenBounded) {
+            this.advance();
+            this.expect(TokenType.Less);
+            const inner = this.parseType();
+            this.expect(TokenType.Comma);
+            const max = this.parseIntValue();
+            this.expect(TokenType.Greater);
+            return { kind: 'token_bounded', inner, max };
+        }
+        // Float -- could be Float or Float(min..max)
+        if (token.type === TokenType.Float) {
+            this.advance();
+            if (this.check(TokenType.LParen)) {
+                this.advance();
+                const min = this.parseNumericValue();
+                this.expect(TokenType.DotDot);
+                const max = this.parseNumericValue();
+                this.expect(TokenType.RParen);
+                return { kind: 'primitive_range', name: 'Float', min, max };
+            }
+            return { kind: 'primitive', name: 'Float' };
+        }
+        // enum(val1, val2, ...)
+        if (token.type === TokenType.Enum) {
+            this.advance();
+            this.expect(TokenType.LParen);
+            const values = [];
+            values.push(this.expectIdentifierOrKeyword());
+            while (this.check(TokenType.Comma)) {
+                this.advance();
+                values.push(this.expectIdentifierOrKeyword());
+            }
+            this.expect(TokenType.RParen);
+            return { kind: 'enum', values };
+        }
+        // Primitives
+        if (token.type === TokenType.String) {
+            this.advance();
+            return { kind: 'primitive', name: 'String' };
+        }
+        if (token.type === TokenType.Int) {
+            this.advance();
+            return { kind: 'primitive', name: 'Int' };
+        }
+        if (token.type === TokenType.Bool) {
+            this.advance();
+            return { kind: 'primitive', name: 'Bool' };
+        }
+        // Domain types
+        if (token.type === TokenType.FilePath) {
+            this.advance();
+            return { kind: 'domain', name: 'FilePath' };
+        }
+        if (token.type === TokenType.FileDiff) {
+            this.advance();
+            return { kind: 'domain', name: 'FileDiff' };
+        }
+        if (token.type === TokenType.TestFile) {
+            this.advance();
+            return { kind: 'domain', name: 'TestFile' };
+        }
+        if (token.type === TokenType.IssueRef) {
+            this.advance();
+            return { kind: 'domain', name: 'IssueRef' };
+        }
+        throw this.error(`Expected type, got '${token.value}'`);
+    }
+    // Parses a type that could be an inline struct: Name { fields }
+    parseTypeOrInlineStruct() {
+        // Check for Identifier followed by '{' -- inline struct
+        if (this.current().type === TokenType.Identifier && this.peekType(1) === TokenType.LBrace) {
+            const name = this.expectIdentifier();
+            this.expect(TokenType.LBrace);
+            const fields = this.parseFields();
+            this.expect(TokenType.RBrace);
+            return { kind: 'struct', name, fields };
+        }
+        return this.parseType();
+    }
+    // --- Fields -------------------------------------------------
+    parseFields() {
+        const fields = [];
+        while (!this.check(TokenType.RBrace)) {
+            const loc = this.current().location;
+            const name = this.expectIdentifierOrKeyword();
+            this.expect(TokenType.Colon);
+            const type = this.parseTypeOrInlineStruct();
+            fields.push({ name, type, location: loc });
+        }
+        return fields;
+    }
+    // --- Helpers ------------------------------------------------
+    parseTokenValue() {
+        const token = this.current();
+        if (token.type === TokenType.IntegerLiteral) {
+            this.advance();
+            return parseInt(token.value, 10);
+        }
+        if (token.type === TokenType.KIntegerLiteral) {
+            this.advance();
+            // parseInt("5k", 10) returns 5 per the JS spec: parseInt stops at first non-digit.
+            return parseInt(token.value, 10) * 1000;
+        }
+        throw this.error(`Expected integer or k-integer, got '${token.value}'`);
+    }
+    parseIntValue() {
+        const token = this.current();
+        if (token.type === TokenType.IntegerLiteral) {
+            this.advance();
+            return parseInt(token.value, 10);
+        }
+        throw this.error(`Expected integer, got '${token.value}'`);
+    }
+    parseNumericValue() {
+        const token = this.current();
+        if (token.type === TokenType.IntegerLiteral) {
+            this.advance();
+            return parseInt(token.value, 10);
+        }
+        if (token.type === TokenType.FloatLiteral) {
+            this.advance();
+            return parseFloat(token.value);
+        }
+        throw this.error(`Expected number, got '${token.value}'`);
+    }
+    /**
+     * Strict identifier: only accepts TokenType.Identifier.
+     * Used for declaration names (context, node, edge, graph), produces names,
+     * context ref context-part, graph flow nodes, edge source/target.
+     * These are PascalCase by convention and must not collide with keywords.
+     */
+    expectIdentifier() {
+        const token = this.current();
+        if (token.type === TokenType.Identifier) {
+            this.advance();
+            return token.value;
+        }
+        throw this.error(`Expected identifier, got '${token.value}' (${token.type})`);
+    }
+    /**
+     * Permissive identifier: accepts TokenType.Identifier OR any keyword token.
+     * Used for field names, tool names, enum values, transform field arguments,
+     * condition field names -- positions where a keyword-like word is valid as a name.
+     */
+    expectIdentifierOrKeyword() {
+        const token = this.current();
+        if (token.type === TokenType.Identifier || KEYWORD_TYPES.has(token.type)) {
+            this.advance();
+            return token.value;
+        }
+        throw this.error(`Expected identifier, got '${token.value}' (${token.type})`);
+    }
+    expect(type) {
+        const token = this.current();
+        if (token.type !== type) {
+            throw this.error(`Expected '${type}', got '${token.value}' (${token.type})`, 'PARSE_UNEXPECTED_TOKEN');
+        }
+        this.advance();
+        return token;
+    }
+    check(type) {
+        return this.current().type === type;
+    }
+    current() {
+        return this.tokens[this.pos];
+    }
+    advance() {
+        const token = this.tokens[this.pos];
+        if (!this.isAtEnd())
+            this.pos++;
+        return token;
+    }
+    peekType(offset) {
+        const idx = this.pos + offset;
+        if (idx < this.tokens.length)
+            return this.tokens[idx].type;
+        return undefined;
+    }
+    isAtEnd() {
+        return this.current().type === TokenType.EOF;
+    }
+    error(message, code = 'PARSE_UNEXPECTED_TOKEN') {
+        return new GraftError(message, this.current().location, 'error', code);
+    }
+}