namel3ss 0.1.0a0__py3-none-any.whl

namel3ss/lint/semantic.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from typing import List, Set
+
+from namel3ss.ir import nodes as ir
+from namel3ss.lint.types import Finding
+
+
+def lint_semantic(program_ir: ir.Program) -> List[Finding]:
+    findings: List[Finding] = []
+    flow_names: Set[str] = {flow.name for flow in program_ir.flows}
+    record_names: Set[str] = {record.name for record in program_ir.records}
+    for page in program_ir.pages:
+        for item in page.items:
+            if isinstance(item, ir.ButtonItem):
+                if item.flow_name not in flow_names:
+                    findings.append(
+                        Finding(
+                            code="refs.unknown_flow",
+                            message=f"Button references unknown flow '{item.flow_name}'",
+                            line=item.line,
+                            column=item.column,
+                        )
+                    )
+            if isinstance(item, ir.FormItem):
+                if item.record_name not in record_names:
+                    findings.append(
+                        Finding(
+                            code="refs.unknown_record",
+                            message=f"Form references unknown record '{item.record_name}'",
+                            line=item.line,
+                            column=item.column,
+                        )
+                    )
+            if isinstance(item, ir.TableItem):
+                if item.record_name not in record_names:
+                    findings.append(
+                        Finding(
+                            code="refs.unknown_record",
+                            message=f"Table references unknown record '{item.record_name}'",
+                            line=item.line,
+                            column=item.column,
+                        )
+                    )
+    return findings

namel3ss/lint/text_scan.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import re
+from typing import List
+
+from namel3ss.lint.types import Finding
+
+
+LEGACY_DECL = re.compile(r'^(flow|page|record|ai|agent|tool)\s+is\s+"')
+ONE_LINE_BUTTON = re.compile(r'^\s*button\s+"[^"]+"\s+calls\s+flow\s+"[^"]+"\s*$')
+PAGE_HEADER = re.compile(r'^\s*page\s+"[^"]+"\s*:\s*$')
+FORBIDDEN_PAGE_TOKENS = {
+    "let",
+    "set",
+    "if",
+    "match",
+    "repeat",
+    "for",
+    "try",
+    "return",
+    "ask",
+    "run",
+    "save",
+    "find",
+}
+
+
+def scan_text(lines: List[str]) -> List[Finding]:
+    findings: List[Finding] = []
+    page_indent = None
+    for idx, line in enumerate(lines, start=1):
+        if LEGACY_DECL.search(line):
+            findings.append(
+                Finding(
+                    code="grammar.decl_uses_is",
+                    message="Declaration uses 'is'; use: <keyword> \"name\":",
+                    line=idx,
+                    column=1,
+                )
+            )
+        if ONE_LINE_BUTTON.search(line):
+            findings.append(
+                Finding(
+                    code="ui.button_one_line_forbidden",
+                    message='Buttons must use a block form: button "X": NEWLINE indent calls flow "Y"',
+                    line=idx,
+                    column=1,
+                )
+            )
+        if PAGE_HEADER.match(line):
+            page_indent = len(line) - len(line.lstrip(" "))
+            continue
+        if page_indent is not None:
+            if line.strip() == "":
+                continue
+            current_indent = len(line) - len(line.lstrip(" "))
+            if current_indent <= page_indent:
+                page_indent = None
+                continue
+            token = line.strip().split()[0].lower()
+            if token in FORBIDDEN_PAGE_TOKENS:
+                findings.append(
+                    Finding(
+                        code="page.imperative_not_allowed",
+                        message=f"Pages are declarative only; '{token}' is not allowed inside page blocks.",
+                        line=idx,
+                        column=current_indent + 1,
+                    )
+                )
+    return findings

namel3ss/lint/types.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class Finding:
+    code: str
+    message: str
+    line: Optional[int]
+    column: Optional[int]
+    severity: str = "error"
+
+    def to_dict(self) -> dict:
+        return {
+            "code": self.code,
+            "message": self.message,
+            "line": self.line,
+            "column": self.column,
+            "severity": self.severity,
+        }

namel3ss/parser/__init__.py

@@ -0,0 +1,3 @@
+"""Parsing pipeline for Namel3ss."""
+
+from namel3ss.parser.core import Parser, parse  # noqa: F401

namel3ss/parser/agent.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+from namel3ss.ast import nodes as ast
+from namel3ss.errors.base import Namel3ssError
+
+
+def parse_agent_decl(parser) -> ast.AgentDecl:
+    agent_tok = parser._advance()
+    name_tok = parser._expect("STRING", "Expected agent name string")
+    parser._expect("COLON", "Expected ':' after agent name")
+    parser._expect("NEWLINE", "Expected newline after agent header")
+    parser._expect("INDENT", "Expected indented agent body")
+    ai_name = None
+    system_prompt = None
+    while parser._current().type != "DEDENT":
+        if parser._match("NEWLINE"):
+            continue
+        key_tok = parser._current()
+        if key_tok.type == "AI":
+            parser._advance()
+            parser._expect("IS", "Expected 'is' after ai")
+            ai_tok = parser._expect("STRING", "Expected AI profile name")
+            ai_name = ai_tok.value
+        elif key_tok.type == "SYSTEM_PROMPT":
+            parser._advance()
+            parser._expect("IS", "Expected 'is' after system_prompt")
+            sp_tok = parser._expect("STRING", "Expected system_prompt string")
+            system_prompt = sp_tok.value
+        else:
+            raise Namel3ssError("Unknown field in agent declaration", line=key_tok.line, column=key_tok.column)
+        parser._match("NEWLINE")
+    parser._expect("DEDENT", "Expected end of agent body")
+    if ai_name is None:
+        raise Namel3ssError("Agent requires an AI profile", line=agent_tok.line, column=agent_tok.column)
+    return ast.AgentDecl(name=name_tok.value, ai_name=ai_name, system_prompt=system_prompt, line=agent_tok.line, column=agent_tok.column)
+
+
+def parse_run_agent_stmt(parser) -> ast.RunAgentStmt:
+    run_tok = parser._advance()
+    if not parser._match("AGENT"):
+        raise Namel3ssError("Expected 'agent' after run", line=run_tok.line, column=run_tok.column)
+    name_tok = parser._expect("STRING", "Expected agent name string")
+    parser._expect("WITH", "Expected 'with' in run agent")
+    parser._expect("INPUT", "Expected 'input' in run agent")
+    parser._expect("COLON", "Expected ':' after input")
+    input_expr = parser._parse_expression()
+    parser._expect("AS", "Expected 'as' to bind agent result")
+    target_tok = parser._expect("IDENT", "Expected target identifier after 'as'")
+    return ast.RunAgentStmt(agent_name=name_tok.value, input_expr=input_expr, target=target_tok.value, line=run_tok.line, column=run_tok.column)
+
+
+def parse_run_agents_parallel(parser) -> ast.RunAgentsParallelStmt:
+    run_tok = parser._advance()
+    if not parser._match("AGENTS"):
+        raise Namel3ssError("Expected 'agents' after run", line=run_tok.line, column=run_tok.column)
+    parser._expect("IN", "Expected 'in'")
+    parser._expect("PARALLEL", "Expected 'parallel'")
+    parser._expect("COLON", "Expected ':' after parallel header")
+    parser._expect("NEWLINE", "Expected newline after parallel header")
+    parser._expect("INDENT", "Expected indented parallel block")
+    entries: list[ast.ParallelAgentEntry] = []
+    while parser._current().type != "DEDENT":
+        if parser._match("NEWLINE"):
+            continue
+        parser._expect("AGENT", "Expected 'agent' in parallel block")
+        name_tok = parser._expect("STRING", "Expected agent name string")
+        parser._expect("WITH", "Expected 'with' in agent entry")
+        parser._expect("INPUT", "Expected 'input' in agent entry")
+        parser._expect("COLON", "Expected ':' after input")
+        input_expr = parser._parse_expression()
+        entries.append(ast.ParallelAgentEntry(agent_name=name_tok.value, input_expr=input_expr, line=name_tok.line, column=name_tok.column))
+        parser._match("NEWLINE")
+    parser._expect("DEDENT", "Expected end of parallel agents block")
+    if not entries:
+        raise Namel3ssError("Parallel agent block requires at least one entry", line=run_tok.line, column=run_tok.column)
+    parser._expect("AS", "Expected 'as' after parallel block")
+    target_tok = parser._expect("IDENT", "Expected target identifier after 'as'")
+    return ast.RunAgentsParallelStmt(entries=entries, target=target_tok.value, line=run_tok.line, column=run_tok.column)

namel3ss/parser/ai.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+from namel3ss.ast import nodes as ast_nodes
+from namel3ss.errors.base import Namel3ssError
+
+
+def parse_ai_decl(parser) -> ast_nodes.AIDecl:
+    ai_tok = parser._advance()
+    name_tok = parser._expect("STRING", "Expected AI name string")
+    parser._expect("COLON", "Expected ':' after AI name")
+    parser._expect("NEWLINE", "Expected newline after AI header")
+    parser._expect("INDENT", "Expected indented AI body")
+    model = None
+    provider = None
+    system_prompt = None
+    exposed_tools: list[str] = []
+    memory = ast_nodes.AIMemory(line=ai_tok.line, column=ai_tok.column)
+    while parser._current().type != "DEDENT":
+        if parser._match("NEWLINE"):
+            continue
+        key_tok = parser._current()
+        if key_tok.type == "MODEL":
+            parser._advance()
+            parser._expect("IS", "Expected 'is' after model")
+            value_tok = parser._expect("STRING", "Expected model string")
+            model = value_tok.value
+        elif key_tok.type == "PROVIDER":
+            parser._advance()
+            parser._expect("IS", "Expected 'is' after provider")
+            value_tok = parser._expect("STRING", "Expected provider string")
+            provider = value_tok.value
+        elif key_tok.type == "SYSTEM_PROMPT":
+            parser._advance()
+            parser._expect("IS", "Expected 'is' after system_prompt")
+            value_tok = parser._expect("STRING", "Expected system_prompt string")
+            system_prompt = value_tok.value
+        elif key_tok.type == "TOOLS":
+            parser._advance()
+            parser._expect("COLON", "Expected ':' after tools")
+            parser._expect("NEWLINE", "Expected newline after tools:")
+            parser._expect("INDENT", "Expected indented tools block")
+            while parser._current().type != "DEDENT":
+                if parser._match("NEWLINE"):
+                    continue
+                if parser._match("EXPOSE"):
+                    tool_tok = parser._expect("STRING", "Expected tool name string")
+                    tool_name = tool_tok.value
+                    if tool_name in exposed_tools:
+                        raise Namel3ssError(f"Duplicate tool exposure '{tool_name}'", line=tool_tok.line, column=tool_tok.column)
+                    exposed_tools.append(tool_name)
+                else:
+                    raise Namel3ssError("Unknown entry in tools block", line=parser._current().line, column=parser._current().column)
+                parser._match("NEWLINE")
+            parser._expect("DEDENT", "Expected end of tools block")
+        elif key_tok.type == "MEMORY":
+            parser._advance()
+            parser._expect("COLON", "Expected ':' after memory")
+            parser._expect("NEWLINE", "Expected newline after memory:")
+            parser._expect("INDENT", "Expected indented memory block")
+            while parser._current().type != "DEDENT":
+                if parser._match("NEWLINE"):
+                    continue
+                mem_key = parser._current()
+                if mem_key.type == "SHORT_TERM":
+                    parser._advance()
+                    parser._expect("IS", "Expected 'is' after short_term")
+                    value_tok = parser._expect("NUMBER", "short_term must be a number literal")
+                    if not isinstance(value_tok.value, int) or value_tok.value < 0:
+                        raise Namel3ssError("short_term must be a non-negative integer", line=value_tok.line, column=value_tok.column)
+                    memory.short_term = value_tok.value
+                elif mem_key.type == "SEMANTIC":
+                    parser._advance()
+                    parser._expect("IS", "Expected 'is' after semantic")
+                    bool_tok = parser._expect("BOOLEAN", "semantic must be true/false literal")
+                    memory.semantic = bool_tok.value
+                elif mem_key.type == "PROFILE":
+                    parser._advance()
+                    parser._expect("IS", "Expected 'is' after profile")
+                    bool_tok = parser._expect("BOOLEAN", "profile must be true/false literal")
+                    memory.profile = bool_tok.value
+                else:
+                    raise Namel3ssError("Unknown memory field", line=mem_key.line, column=mem_key.column)
+                parser._match("NEWLINE")
+            parser._expect("DEDENT", "Expected end of memory block")
+        else:
+            raise Namel3ssError("Unknown field in AI declaration", line=key_tok.line, column=key_tok.column)
+        parser._match("NEWLINE")
+    parser._expect("DEDENT", "Expected end of AI body")
+    if model is None:
+        raise Namel3ssError("AI declaration requires a model", line=ai_tok.line, column=ai_tok.column)
+    return ast_nodes.AIDecl(
+        name=name_tok.value,
+        model=model,
+        provider=provider,
+        system_prompt=system_prompt,
+        exposed_tools=exposed_tools,
+        memory=memory,
+        line=ai_tok.line,
+        column=ai_tok.column,
+    )
+
+
+def parse_ask_stmt(parser) -> ast_nodes.AskAIStmt:
+    ask_tok = parser._advance()
+    parser._expect("AI", "Expected 'ai' after 'ask'")
+    name_tok = parser._expect("STRING", "Expected AI name string")
+    parser._expect("WITH", "Expected 'with' in ask ai statement")
+    parser._expect("INPUT", "Expected 'input' in ask ai statement")
+    parser._expect("COLON", "Expected ':' after input")
+    input_expr = parser._parse_expression()
+    parser._expect("AS", "Expected 'as' to bind AI result")
+    target_tok = parser._expect("IDENT", "Expected target identifier after 'as'")
+    return ast_nodes.AskAIStmt(ai_name=name_tok.value, input_expr=input_expr, target=target_tok.value, line=ask_tok.line, column=ask_tok.column)

namel3ss/parser/constraints.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from namel3ss.ast import nodes as ast
+from namel3ss.errors.base import Namel3ssError
+
+
+def parse_field_constraint(parser) -> ast.FieldConstraint:
+    tok = parser._current()
+    if parser._match("BE"):
+        if parser._match("PRESENT"):
+            return ast.FieldConstraint(kind="present", line=tok.line, column=tok.column)
+        if parser._match("UNIQUE"):
+            return ast.FieldConstraint(kind="unique", line=tok.line, column=tok.column)
+        if parser._match("GREATER"):
+            parser._expect("THAN", "Expected 'than' after 'greater'")
+            expr = parser._parse_expression()
+            return ast.FieldConstraint(kind="gt", expression=expr, line=tok.line, column=tok.column)
+        if parser._match("LESS"):
+            parser._expect("THAN", "Expected 'than' after 'less'")
+            expr = parser._parse_expression()
+            return ast.FieldConstraint(kind="lt", expression=expr, line=tok.line, column=tok.column)
+    if parser._match("MATCH"):
+        parser._expect("PATTERN", "Expected 'pattern'")
+        pattern_tok = parser._expect("STRING", "Expected pattern string")
+        return ast.FieldConstraint(kind="pattern", pattern=pattern_tok.value, line=tok.line, column=tok.column)
+    if parser._match("HAVE"):
+        parser._expect("LENGTH", "Expected 'length'")
+        parser._expect("AT", "Expected 'at'")
+        if parser._match("LEAST"):
+            expr = parser._parse_expression()
+            return ast.FieldConstraint(kind="len_min", expression=expr, line=tok.line, column=tok.column)
+        if parser._match("MOST"):
+            expr = parser._parse_expression()
+            return ast.FieldConstraint(kind="len_max", expression=expr, line=tok.line, column=tok.column)
+        tok = parser._current()
+        raise Namel3ssError("Expected 'least' or 'most' after length", line=tok.line, column=tok.column)
+    raise Namel3ssError("Unknown constraint", line=tok.line, column=tok.column)

namel3ss/parser/core.py

@@ -0,0 +1,166 @@
+from __future__ import annotations
+
+from typing import List, Set
+
+from namel3ss.ast import nodes as ast
+from namel3ss.lexer.lexer import Lexer
+from namel3ss.lexer.tokens import Token
+from namel3ss.parser import tokens as token_ops
+from namel3ss.parser.constraints import parse_field_constraint
+from namel3ss.parser.expressions import (
+    parse_comparison,
+    parse_expression,
+    parse_not,
+    parse_or,
+    parse_primary,
+    parse_state_path,
+)
+from namel3ss.parser.expressions import parse_and as parse_and_expr
+from namel3ss.parser.flow import parse_block, parse_flow, parse_statements
+from namel3ss.parser.pages import parse_page, parse_page_item
+from namel3ss.parser.program import parse_program
+from namel3ss.parser.records import parse_record, parse_record_fields, type_from_token
+from namel3ss.parser.statements import (
+    parse_find,
+    parse_for_each,
+    parse_if,
+    parse_let,
+    parse_match,
+    parse_repeat,
+    parse_return,
+    parse_save,
+    parse_set,
+    parse_statement,
+    parse_target,
+    parse_try,
+    validate_match_pattern,
+)
+
+
+class Parser:
+    def __init__(self, tokens: List[Token]) -> None:
+        self.tokens = tokens
+        self.position = 0
+
+    @classmethod
+    def parse(cls, source: str) -> ast.Program:
+        lexer = Lexer(source)
+        tokens = lexer.tokenize()
+        parser = cls(tokens)
+        program = parser._parse_program()
+        parser._expect("EOF")
+        return program
+
+    # Token helpers
+    def _current(self) -> Token:
+        return token_ops.current(self)
+
+    def _advance(self) -> Token:
+        return token_ops.advance(self)
+
+    def _match(self, *types: str) -> bool:
+        return token_ops.match(self, *types)
+
+    def _expect(self, token_type: str, message=None) -> Token:
+        return token_ops.expect(self, token_type, message)
+
+    # Program level
+    def _parse_program(self) -> ast.Program:
+        return parse_program(self)
+
+    # Flow and blocks
+    def _parse_flow(self) -> ast.Flow:
+        return parse_flow(self)
+
+    def _parse_statements(self, until: Set[str]) -> List[ast.Statement]:
+        return parse_statements(self, until)
+
+    def _parse_block(self) -> List[ast.Statement]:
+        return parse_block(self)
+
+    # Statements
+    def _parse_statement(self) -> ast.Statement:
+        return parse_statement(self)
+
+    def _parse_let(self) -> ast.Let:
+        return parse_let(self)
+
+    def _parse_set(self) -> ast.Set:
+        return parse_set(self)
+
+    def _parse_if(self) -> ast.If:
+        return parse_if(self)
+
+    def _parse_return(self) -> ast.Return:
+        return parse_return(self)
+
+    def _parse_repeat(self) -> ast.Repeat:
+        return parse_repeat(self)
+
+    def _parse_for_each(self) -> ast.ForEach:
+        return parse_for_each(self)
+
+    def _parse_match(self) -> ast.Match:
+        return parse_match(self)
+
+    def _parse_try(self) -> ast.TryCatch:
+        return parse_try(self)
+
+    def _parse_save(self) -> ast.Save:
+        return parse_save(self)
+
+    def _parse_find(self) -> ast.Find:
+        return parse_find(self)
+
+    def _parse_target(self) -> ast.Assignable:
+        return parse_target(self)
+
+    def _validate_match_pattern(self, pattern: ast.Expression) -> None:
+        return validate_match_pattern(self, pattern)
+
+    # Expressions
+    def _parse_expression(self) -> ast.Expression:
+        return parse_expression(self)
+
+    def _parse_or(self) -> ast.Expression:
+        return parse_or(self)
+
+    def _parse_and(self) -> ast.Expression:
+        return parse_and_expr(self)
+
+    def _parse_not(self) -> ast.Expression:
+        return parse_not(self)
+
+    def _parse_comparison(self) -> ast.Expression:
+        return parse_comparison(self)
+
+    def _parse_primary(self) -> ast.Expression:
+        return parse_primary(self)
+
+    def _parse_state_path(self) -> ast.StatePath:
+        return parse_state_path(self)
+
+    # Records and constraints
+    def _parse_record(self) -> ast.RecordDecl:
+        return parse_record(self)
+
+    def _parse_record_fields(self) -> List[ast.FieldDecl]:
+        return parse_record_fields(self)
+
+    def _parse_field_constraint(self) -> ast.FieldConstraint:
+        return parse_field_constraint(self)
+
+    @staticmethod
+    def _type_from_token(tok: Token) -> str:
+        return type_from_token(tok)
+
+    # Pages
+    def _parse_page(self) -> ast.PageDecl:
+        return parse_page(self)
+
+    def _parse_page_item(self) -> ast.PageItem:
+        return parse_page_item(self)
+
+
+def parse(source: str) -> ast.Program:
+    return Parser.parse(source)

namel3ss/parser/expressions.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+from typing import List
+
+from namel3ss.ast import nodes as ast
+from namel3ss.errors.base import Namel3ssError
+
+
+def parse_expression(parser) -> ast.Expression:
+    return parse_or(parser)
+
+
+def parse_or(parser) -> ast.Expression:
+    expr = parse_and(parser)
+    while parser._match("OR"):
+        op_tok = parser.tokens[parser.position - 1]
+        right = parse_and(parser)
+        expr = ast.BinaryOp(op="or", left=expr, right=right, line=op_tok.line, column=op_tok.column)
+    return expr
+
+
+def parse_and(parser) -> ast.Expression:
+    expr = parse_not(parser)
+    while parser._match("AND"):
+        op_tok = parser.tokens[parser.position - 1]
+        right = parse_not(parser)
+        expr = ast.BinaryOp(op="and", left=expr, right=right, line=op_tok.line, column=op_tok.column)
+    return expr
+
+
+def parse_not(parser) -> ast.Expression:
+    if parser._match("NOT"):
+        tok = parser.tokens[parser.position - 1]
+        operand = parse_not(parser)
+        return ast.UnaryOp(op="not", operand=operand, line=tok.line, column=tok.column)
+    return parse_comparison(parser)
+
+
+def parse_comparison(parser) -> ast.Expression:
+    left = parse_primary(parser)
+    if not parser._match("IS"):
+        return left
+    is_tok = parser.tokens[parser.position - 1]
+    if parser._match("GREATER"):
+        parser._expect("THAN", "Expected 'than' after 'is greater'")
+        right = parse_primary(parser)
+        return ast.Comparison(kind="gt", left=left, right=right, line=is_tok.line, column=is_tok.column)
+    if parser._match("LESS"):
+        parser._expect("THAN", "Expected 'than' after 'is less'")
+        right = parse_primary(parser)
+        return ast.Comparison(kind="lt", left=left, right=right, line=is_tok.line, column=is_tok.column)
+    if parser._match("EQUAL"):
+        if parser._match("TO"):
+            pass
+        right = parse_primary(parser)
+        return ast.Comparison(kind="eq", left=left, right=right, line=is_tok.line, column=is_tok.column)
+    right = parse_primary(parser)
+    return ast.Comparison(kind="eq", left=left, right=right, line=is_tok.line, column=is_tok.column)
+
+
+def parse_primary(parser) -> ast.Expression:
+    tok = parser._current()
+    if tok.type == "NUMBER":
+        parser._advance()
+        return ast.Literal(value=tok.value, line=tok.line, column=tok.column)
+    if tok.type == "STRING":
+        parser._advance()
+        return ast.Literal(value=tok.value, line=tok.line, column=tok.column)
+    if tok.type == "BOOLEAN":
+        parser._advance()
+        return ast.Literal(value=tok.value, line=tok.line, column=tok.column)
+    if tok.type in {"IDENT", "INPUT"}:
+        parser._advance()
+        attrs: List[str] = []
+        while parser._match("DOT"):
+            attr_tok = parser._expect("IDENT", "Expected identifier after '.'")
+            attrs.append(attr_tok.value)
+        if attrs:
+            return ast.AttrAccess(base=tok.value, attrs=attrs, line=tok.line, column=tok.column)
+        return ast.VarReference(name=tok.value, line=tok.line, column=tok.column)
+    if tok.type == "STATE":
+        return parse_state_path(parser)
+    if tok.type == "LPAREN":
+        parser._advance()
+        expr = parse_expression(parser)
+        parser._expect("RPAREN", "Expected ')'")
+        return expr
+    if tok.type == "ASK":
+        raise Namel3ssError(
+            'AI calls are statements. Use: ask ai "name" with input: <expr> as <target>.',
+            line=tok.line,
+            column=tok.column,
+        )
+    raise Namel3ssError("Unexpected expression", line=tok.line, column=tok.column)
+
+
+def parse_state_path(parser) -> ast.StatePath:
+    state_tok = parser._expect("STATE", "Expected 'state'")
+    path: List[str] = []
+    while parser._match("DOT"):
+        ident_tok = parser._expect("IDENT", "Expected identifier after '.'")
+        path.append(ident_tok.value)
+    if not path:
+        raise Namel3ssError("Expected state path after 'state'", line=state_tok.line, column=state_tok.column)
+    return ast.StatePath(path=path, line=state_tok.line, column=state_tok.column)