namel3ss 0.1.0a0__py3-none-any.whl

namel3ss/ir/model/expressions.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List, Union
+
+from namel3ss.ir.model.base import Expression
+
+
+@dataclass
+class Literal(Expression):
+    value: Union[str, int, bool]
+
+
+@dataclass
+class VarReference(Expression):
+    name: str
+
+
+@dataclass
+class AttrAccess(Expression):
+    base: str
+    attrs: List[str]
+
+
+@dataclass
+class StatePath(Expression):
+    path: List[str]
+
+
+@dataclass
+class UnaryOp(Expression):
+    op: str
+    operand: Expression
+
+
+@dataclass
+class BinaryOp(Expression):
+    op: str
+    left: Expression
+    right: Expression
+
+
+@dataclass
+class Comparison(Expression):
+    kind: str
+    left: Expression
+    right: Expression
+
+
+Assignable = Union[VarReference, StatePath]

namel3ss/ir/model/pages.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List
+
+from namel3ss.ir.model.base import Node
+
+
+@dataclass
+class Page(Node):
+    name: str
+    items: List["PageItem"]
+
+
+@dataclass
+class PageItem(Node):
+    pass
+
+
+@dataclass
+class TitleItem(PageItem):
+    value: str
+
+
+@dataclass
+class TextItem(PageItem):
+    value: str
+
+
+@dataclass
+class FormItem(PageItem):
+    record_name: str
+
+
+@dataclass
+class TableItem(PageItem):
+    record_name: str
+
+
+@dataclass
+class ButtonItem(PageItem):
+    label: str
+    flow_name: str

namel3ss/ir/model/program.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Dict, List
+
+from namel3ss.ir.model.base import Node
+from namel3ss.ir.model.statements import Statement
+from namel3ss.ir.model.pages import Page
+from namel3ss.ir.model.ai import AIDecl
+from namel3ss.ir.model.agents import AgentDecl
+from namel3ss.ir.model.tools import ToolDecl
+from namel3ss.schema import records as schema
+
+
+@dataclass
+class Flow(Node):
+    name: str
+    body: List[Statement]
+
+
+@dataclass
+class Program(Node):
+    records: List[schema.RecordSchema]
+    flows: List[Flow]
+    pages: List[Page]
+    ais: Dict[str, AIDecl]
+    tools: Dict[str, ToolDecl]
+    agents: Dict[str, AgentDecl]

namel3ss/ir/model/statements.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List
+
+from namel3ss.ir.model.base import Node, Statement
+from namel3ss.ir.model.expressions import Assignable, Expression
+
+
+@dataclass
+class Let(Statement):
+    name: str
+    expression: Expression
+    constant: bool
+
+
+@dataclass
+class Set(Statement):
+    target: Assignable
+    expression: Expression
+
+
+@dataclass
+class If(Statement):
+    condition: Expression
+    then_body: List[Statement]
+    else_body: List[Statement]
+
+
+@dataclass
+class Return(Statement):
+    expression: Expression
+
+
+@dataclass
+class Repeat(Statement):
+    count: Expression
+    body: List[Statement]
+
+
+@dataclass
+class ForEach(Statement):
+    name: str
+    iterable: Expression
+    body: List[Statement]
+
+
+@dataclass
+class MatchCase(Node):
+    pattern: Expression
+    body: List[Statement]
+
+
+@dataclass
+class Match(Statement):
+    expression: Expression
+    cases: List[MatchCase]
+    otherwise: List[Statement] | None
+
+
+@dataclass
+class TryCatch(Statement):
+    try_body: List[Statement]
+    catch_var: str
+    catch_body: List[Statement]
+
+
+@dataclass
+class Save(Statement):
+    record_name: str
+
+
+@dataclass
+class Find(Statement):
+    record_name: str
+    predicate: Expression

namel3ss/ir/model/tools.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from namel3ss.ir.model.base import Node
+
+
+@dataclass
+class ToolDecl(Node):
+    name: str
+    kind: str

namel3ss/ir/nodes.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+from namel3ss.ir.lowering import lower_program, lower_flow
+from namel3ss.ir.model import (  # noqa: F401
+    AIMemory,
+    AIDecl,
+    AgentDecl,
+    AskAIStmt,
+    Assignable,
+    AttrAccess,
+    BinaryOp,
+    ButtonItem,
+    Comparison,
+    Expression,
+    Find,
+    Flow,
+    ForEach,
+    FormItem,
+    If,
+    Let,
+    Literal,
+    Match,
+    MatchCase,
+    Node,
+    Page,
+    PageItem,
+    ParallelAgentEntry,
+    Program,
+    Repeat,
+    Return,
+    RunAgentStmt,
+    RunAgentsParallelStmt,
+    Save,
+    Set,
+    StatePath,
+    Statement,
+    TableItem,
+    TextItem,
+    TitleItem,
+    ToolDecl,
+    TryCatch,
+    UnaryOp,
+    VarReference,
+)
+
+__all__ = [
+    "AIMemory",
+    "AIDecl",
+    "AgentDecl",
+    "AskAIStmt",
+    "Assignable",
+    "AttrAccess",
+    "BinaryOp",
+    "ButtonItem",
+    "Comparison",
+    "Expression",
+    "Find",
+    "Flow",
+    "ForEach",
+    "FormItem",
+    "If",
+    "Let",
+    "Literal",
+    "Match",
+    "MatchCase",
+    "Node",
+    "Page",
+    "PageItem",
+    "ParallelAgentEntry",
+    "Program",
+    "Repeat",
+    "Return",
+    "RunAgentStmt",
+    "RunAgentsParallelStmt",
+    "Save",
+    "Set",
+    "StatePath",
+    "Statement",
+    "TableItem",
+    "TextItem",
+    "TitleItem",
+    "ToolDecl",
+    "TryCatch",
+    "UnaryOp",
+    "VarReference",
+    "lower_program",
+    "lower_flow",
+]

namel3ss/lexer/__init__.py

@@ -0,0 +1,2 @@
+"""Lexical analysis utilities for Namel3ss."""
+

namel3ss/lexer/lexer.py

@@ -0,0 +1,152 @@
+from __future__ import annotations
+
+from typing import List
+
+from namel3ss.errors.base import Namel3ssError
+from namel3ss.lexer.tokens import KEYWORDS, Token
+
+
+class Lexer:
+    """Line-based lexer with indentation awareness."""
+
+    def __init__(self, source: str) -> None:
+        self.source = source
+
+    def tokenize(self) -> List[Token]:
+        tokens: List[Token] = []
+        indent_stack = [0]
+        lines = self.source.splitlines()
+
+        for line_no, raw_line in enumerate(lines, start=1):
+            stripped = raw_line.rstrip("\n")
+            if stripped.strip() == "":
+                continue
+
+            indent = self._leading_spaces(stripped)
+            if indent > indent_stack[-1]:
+                tokens.append(Token("INDENT", None, line_no, 1))
+                indent_stack.append(indent)
+            else:
+                while indent < indent_stack[-1]:
+                    indent_stack.pop()
+                    tokens.append(Token("DEDENT", None, line_no, 1))
+                if indent != indent_stack[-1]:
+                    raise Namel3ssError(
+                        f"Inconsistent indentation (got {indent} spaces, expected {indent_stack[-1]})",
+                        line=line_no,
+                        column=1,
+                    )
+
+            line_tokens = self._scan_line(stripped.lstrip(" "), line_no, indent + 1)
+            tokens.extend(line_tokens)
+            tokens.append(Token("NEWLINE", None, line_no, len(stripped) + 1))
+
+        while len(indent_stack) > 1:
+            indent_stack.pop()
+            tokens.append(Token("DEDENT", None, len(lines), 1))
+
+        tokens.append(Token("EOF", None, len(lines) + 1, 1))
+        return tokens
+
+    @staticmethod
+    def _leading_spaces(text: str) -> int:
+        count = 0
+        for ch in text:
+            if ch == " ":
+                count += 1
+            else:
+                break
+        return count
+
+    def _scan_line(self, text: str, line_no: int, start_col: int) -> List[Token]:
+        tokens: List[Token] = []
+        i = 0
+        column = start_col
+        while i < len(text):
+            ch = text[i]
+            if ch == " ":
+                i += 1
+                column += 1
+                continue
+            if ch == ":":
+                tokens.append(Token("COLON", ":", line_no, column))
+                i += 1
+                column += 1
+                continue
+            if ch == ".":
+                tokens.append(Token("DOT", ".", line_no, column))
+                i += 1
+                column += 1
+                continue
+            if ch == "(":
+                tokens.append(Token("LPAREN", "(", line_no, column))
+                i += 1
+                column += 1
+                continue
+            if ch == ")":
+                tokens.append(Token("RPAREN", ")", line_no, column))
+                i += 1
+                column += 1
+                continue
+            if ch == '"':
+                value, consumed = self._read_string(text[i:], line_no, column)
+                tokens.append(Token("STRING", value, line_no, column))
+                i += consumed
+                column += consumed
+                continue
+            if ch.isdigit():
+                value, consumed = self._read_number(text[i:])
+                tokens.append(Token("NUMBER", value, line_no, column))
+                i += consumed
+                column += consumed
+                continue
+            if ch.isalpha() or ch == "_":
+                value, consumed = self._read_identifier(text[i:])
+                token_type = KEYWORDS.get(value, "IDENT")
+                token_value = self._keyword_value(token_type, value)
+                tokens.append(Token(token_type, token_value, line_no, column))
+                i += consumed
+                column += consumed
+                continue
+
+            raise Namel3ssError(f"Unexpected character '{ch}'", line=line_no, column=column)
+
+        return tokens
+
+    @staticmethod
+    def _read_string(text: str, line: int, column: int) -> tuple[str, int]:
+        assert text[0] == '"'
+        value_chars = []
+        i = 1
+        while i < len(text):
+            ch = text[i]
+            if ch == '"':
+                return "".join(value_chars), i + 1
+            value_chars.append(ch)
+            i += 1
+        raise Namel3ssError("Unterminated string literal", line=line, column=column)
+
+    @staticmethod
+    def _read_number(text: str) -> tuple[int, int]:
+        i = 0
+        digits = []
+        while i < len(text) and text[i].isdigit():
+            digits.append(text[i])
+            i += 1
+        return int("".join(digits)), i
+
+    @staticmethod
+    def _read_identifier(text: str) -> tuple[str, int]:
+        i = 0
+        chars = []
+        while i < len(text) and (text[i].isalnum() or text[i] == "_"):
+            chars.append(text[i])
+            i += 1
+        return "".join(chars), i
+
+    @staticmethod
+    def _keyword_value(token_type: str, raw: str):
+        if token_type == "BOOLEAN":
+            return raw.lower() == "true"
+        return raw
+

namel3ss/lexer/tokens.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+# Reserved words mapped to their token types. Keep each keyword string once to
+# avoid silent overrides; duplicates hide earlier entries and break coverage.
+# When adding new keywords, append here only after confirming the token type is
+# unique and tests cover the new surface.
+KEYWORDS = {
+    "flow": "FLOW",
+    "page": "PAGE",
+    "ai": "AI",
+    "ask": "ASK",
+    "with": "WITH",
+    "input": "INPUT",
+    "as": "AS",
+    "provider": "PROVIDER",
+    "tools": "TOOLS",
+    "expose": "EXPOSE",
+    "tool": "TOOL",
+    "kind": "KIND",
+    "memory": "MEMORY",
+    "short_term": "SHORT_TERM",
+    "semantic": "SEMANTIC",
+    "profile": "PROFILE",
+    "agent": "AGENT",
+    "agents": "AGENTS",
+    "parallel": "PARALLEL",
+    "run": "RUN",
+    "model": "MODEL",
+    "system_prompt": "SYSTEM_PROMPT",
+    "title": "TITLE",
+    "text": "TEXT",
+    "form": "FORM",
+    "table": "TABLE",
+    "button": "BUTTON",
+    "calls": "CALLS",
+    "record": "RECORD",
+    "save": "SAVE",
+    "find": "FIND",
+    "where": "WHERE",
+    "let": "LET",
+    "set": "SET",
+    "return": "RETURN",
+    "repeat": "REPEAT",
+    "up": "UP",
+    "to": "TO",
+    "times": "TIMES",
+    "for": "FOR",
+    "each": "EACH",
+    "in": "IN",
+    "match": "MATCH",
+    "when": "WHEN",
+    "otherwise": "OTHERWISE",
+    "try": "TRY",
+    "catch": "CATCH",
+    "if": "IF",
+    "else": "ELSE",
+    "is": "IS",
+    "greater": "GREATER",
+    "less": "LESS",
+    "equal": "EQUAL",
+    "than": "THAN",
+    "and": "AND",
+    "or": "OR",
+    "not": "NOT",
+    "state": "STATE",
+    "constant": "CONSTANT",
+    "true": "BOOLEAN",
+    "false": "BOOLEAN",
+    "string": "TYPE_STRING",
+    "int": "TYPE_INT",
+    "number": "TYPE_NUMBER",
+    "boolean": "TYPE_BOOLEAN",
+    "json": "TYPE_JSON",
+    "must": "MUST",
+    "be": "BE",
+    "present": "PRESENT",
+    "unique": "UNIQUE",
+    "pattern": "PATTERN",
+    "have": "HAVE",
+    "length": "LENGTH",
+    "at": "AT",
+    "least": "LEAST",
+    "most": "MOST",
+}
+
+
+@dataclass(frozen=True)
+class Token:
+    type: str
+    value: Optional[object]
+    line: int
+    column: int
+
+    def __repr__(self) -> str:  # pragma: no cover - debug helper
+        return f"Token({self.type}, {self.value}, {self.line}:{self.column})"

namel3ss/lint/__init__.py

@@ -0,0 +1,4 @@
+from namel3ss.lint.engine import lint_source
+from namel3ss.lint.types import Finding
+
+__all__ = ["lint_source", "Finding"]

namel3ss/lint/engine.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+from namel3ss.errors.base import Namel3ssError
+from namel3ss.errors.render import format_error
+from namel3ss.ir.nodes import lower_program
+from namel3ss.lexer.tokens import KEYWORDS
+from namel3ss.lint.semantic import lint_semantic
+from namel3ss.lint.text_scan import scan_text
+from namel3ss.lint.types import Finding
+from namel3ss.parser.core import parse
+from namel3ss.ast import nodes as ast
+
+
+def lint_source(source: str) -> list[Finding]:
+    lines = source.splitlines()
+    findings = scan_text(lines)
+
+    ast_program = None
+    try:
+        ast_program = parse(source)
+    except Namel3ssError as err:
+        findings.append(
+            Finding(
+                code="lint.parse_failed",
+                message="Parse failed; showing best-effort lint results.",
+                line=err.line,
+                column=err.column,
+                severity="warning",
+            )
+        )
+        return findings
+
+    findings.extend(_lint_reserved_identifiers(ast_program))
+    flow_names = {flow.name for flow in ast_program.flows}
+    record_names = {record.name for record in ast_program.records}
+
+    try:
+        program_ir = lower_program(ast_program)
+    except Namel3ssError as err:
+        findings.extend(_lint_refs_ast(ast_program, flow_names, record_names))
+        findings.append(
+            Finding(
+                code="lint.parse_failed",
+                message="Lowering failed; showing best-effort lint results.",
+                line=err.line,
+                column=err.column,
+                severity="warning",
+            )
+        )
+        return findings
+
+    findings.extend(lint_semantic(program_ir))
+    return findings
+
+
+def _lint_reserved_identifiers(ast_program) -> list[Finding]:
+    reserved = set(KEYWORDS.keys())
+    findings: list[Finding] = []
+
+    def walk_statements(stmts):
+        for stmt in stmts:
+            if hasattr(stmt, "body"):
+                walk_statements(getattr(stmt, "body"))
+            if hasattr(stmt, "then_body"):
+                walk_statements(stmt.then_body)
+            if hasattr(stmt, "else_body"):
+                walk_statements(stmt.else_body)
+            if hasattr(stmt, "try_body"):
+                walk_statements(stmt.try_body)
+            if hasattr(stmt, "catch_body"):
+                walk_statements(stmt.catch_body)
+            if hasattr(stmt, "cases"):
+                for case in stmt.cases:
+                    walk_statements(case.body)
+            if stmt.__class__.__name__ == "Let":
+                if stmt.name in reserved:
+                    findings.append(
+                        Finding(
+                            code="names.reserved_identifier",
+                            message=f"Identifier '{stmt.name}' is reserved",
+                            line=stmt.line,
+                            column=stmt.column,
+                        )
+                    )
+
+    for flow in ast_program.flows:
+        walk_statements(flow.body)
+    return findings
+
+
+def _lint_refs_ast(ast_program, flow_names: set[str], record_names: set[str]) -> list[Finding]:
+    findings: list[Finding] = []
+    for page in ast_program.pages:
+        for item in page.items:
+            if isinstance(item, ast.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, ast.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, ast.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