Barmaja-PyArduino 2.0.0__py3-none-any.whl

Barmaja_PyArduino/frontend.py

@@ -0,0 +1,611 @@
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+
+from .errors import CompileError, UnsupportedFeatureError
+
+from . import device_packs as _device_packs
+from .api_registry import (
+    CORE_FUNCTIONS, HARDWARE_CLASSES, PUBLIC_API_NAMES, SINGLETONS, arity_range,
+)
+
+# Phase-B keeps structural validation, but all Arduino API arity/public-surface
+# facts now come from the formal Step-12 registry. Language builtins remain
+# compiler-language rules rather than Arduino API entries.
+CORE_CALL_ARITY: dict[str, tuple[int, int | None]] = {
+    name: arity_range(spec.arities) for name, spec in CORE_FUNCTIONS.items()
+}
+
+BUILTIN_CALL_ARITY: dict[str, tuple[int, int | None]] = {
+    "round": (1, 2),
+    "min": (2, None),
+    "max": (2, None),
+    "abs": (1, 1),
+    "int": (1, 1),
+    "float": (1, 1),
+    "bool": (1, 1),
+    "len": (1, 1),
+    "sum": (1, 1),
+    "enumerate": (1, 2),
+}
+
+CONSTRUCTOR_ARITY: dict[str, tuple[int, int | None]] = {
+    name: arity_range(spec.constructor_arities) for name, spec in HARDWARE_CLASSES.items()
+}
+
+METHOD_ARITY: dict[str, dict[str, tuple[int, int | None]]] = {
+    **{
+        cls: {name: arity_range(method.arities) for name, method in spec.methods.items()}
+        for cls, spec in HARDWARE_CLASSES.items()
+    },
+    **{
+        owner: {name: arity_range(method.arities) for name, method in spec.methods.items()}
+        for owner, spec in SINGLETONS.items()
+    },
+}
+
+SUPPORTED_COMPARE_OPS = (ast.Eq, ast.NotEq, ast.Lt, ast.LtE, ast.Gt, ast.GtE)
+SUPPORTED_BIN_OPS = (ast.Add, ast.Sub, ast.Mult, ast.Div, ast.Mod)
+SUPPORTED_AUG_OPS = (ast.Add, ast.Sub, ast.Mult, ast.Div, ast.Mod)
+SUPPORTED_UNARY_OPS = (ast.USub, ast.Not)
+
+
+@dataclass(frozen=True)
+class FrontendModule:
+    """Phase-B result: structurally closed AST plus normalized import surface."""
+
+    tree: ast.Module
+    api_names: frozenset[str]
+    source_imports: tuple[str, ...]
+    main_loop: ast.While
+
+
+def _loc(node: ast.AST) -> dict[str, int | None]:
+    return {
+        "line": getattr(node, "lineno", None),
+        "column": (getattr(node, "col_offset", None) + 1) if getattr(node, "col_offset", None) is not None else None,
+        "end_line": getattr(node, "end_lineno", None),
+        "end_column": getattr(node, "end_col_offset", None),
+    }
+
+
+def _unsupported(message: str, node: ast.AST) -> UnsupportedFeatureError:
+    return UnsupportedFeatureError(message, **_loc(node))
+
+
+def _compile_error(message: str, node: ast.AST) -> CompileError:
+    return CompileError(message, **_loc(node))
+
+
+def _is_true(node: ast.AST) -> bool:
+    return isinstance(node, ast.Constant) and node.value is True
+
+
+def _is_ellipsis_stmt(node: ast.stmt) -> bool:
+    return isinstance(node, ast.Expr) and isinstance(node.value, ast.Constant) and node.value.value is Ellipsis
+
+
+def _is_docstring_stmt(node: ast.stmt) -> bool:
+    return isinstance(node, ast.Expr) and isinstance(node.value, ast.Constant) and isinstance(node.value.value, str)
+
+
+def _is_literal_scalar(node: ast.AST) -> bool:
+    if isinstance(node, ast.UnaryOp) and isinstance(node.op, ast.USub):
+        node = node.operand
+        return isinstance(node, ast.Constant) and isinstance(node.value, (int, float)) and not isinstance(node.value, bool)
+    return isinstance(node, ast.Constant) and isinstance(node.value, (bool, int, float, str))
+
+
+def is_noop_stmt(node: ast.stmt, *, docstring_allowed: bool = False) -> bool:
+    return isinstance(node, ast.Pass) or _is_ellipsis_stmt(node) or (docstring_allowed and _is_docstring_stmt(node))
+
+
+def _arity_text(min_args: int, max_args: int | None) -> str:
+    if max_args is None:
+        return f"at least {min_args} positional arguments"
+    if min_args == max_args:
+        return f"{min_args} positional argument" + ("" if min_args == 1 else "s")
+    return f"{min_args} to {max_args} positional arguments"
+
+
+
+
+def _check_registered_arities(name: str, node: ast.Call, arities: frozenset[int]) -> None:
+    if len(node.args) in arities:
+        return
+    allowed = sorted(arities)
+    if len(allowed) == 1:
+        text = f"{allowed[0]} positional argument" + ("" if allowed[0] == 1 else "s")
+    else:
+        text = "one of " + ", ".join(str(x) for x in allowed[:-1]) + f" or {allowed[-1]} positional arguments"
+    raise _compile_error(f"{name}() accepts {text}.", node)
+
+def _check_arity(name: str, node: ast.Call, rule: tuple[int, int | None]) -> None:
+    min_args, max_args = rule
+    count = len(node.args)
+    if count < min_args or (max_args is not None and count > max_args):
+        raise _compile_error(f"{name}() accepts {_arity_text(min_args, max_args)} in Barmaja PyArduino V1.", node)
+
+
+class FrontendValidator:
+    """Closed structural validator for the 0.6.0 frontend subset.
+
+    This phase deliberately does not resolve ordinary student names or infer
+    types.  Those belong to Steps 5+.  Its job is to guarantee that every AST
+    shape passed onward has an explicit later-phase path and cannot surprise the
+    current analyzer/backend with an unknown node/operator/call shape.
+    """
+
+    def __init__(self) -> None:
+        self.api_names: set[str] = set()
+        self.source_imports: list[str] = []
+        self.function_names: set[str] = set()
+        self.object_classes: dict[str, str] = {}
+        self._created_objects: dict[str, str] = {}
+
+    def validate(self, tree: ast.Module) -> FrontendModule:
+        main_loop: ast.While | None = None
+        main_loop_seen = False
+
+        # Pre-collect declaration shapes so a function body may structurally
+        # reference a hardware object/function declared later at module level.
+        # Execution-order/name availability is resolved in Step 5.
+        for node in tree.body:
+            if isinstance(node, ast.FunctionDef):
+                self.function_names.add(node.name)
+            if (
+                isinstance(node, ast.Assign)
+                and len(node.targets) == 1
+                and isinstance(node.targets[0], ast.Name)
+                and isinstance(node.value, ast.Call)
+                and isinstance(node.value.func, ast.Name)
+                and node.value.func.id in CONSTRUCTOR_ARITY
+            ):
+                self.object_classes[node.targets[0].id] = node.value.func.id
+
+        for index, node in enumerate(tree.body):
+            if isinstance(node, ast.ImportFrom):
+                if main_loop_seen:
+                    raise _compile_error("Nothing may follow the main top-level 'while True:' loop.", node)
+                self._validate_import_from(node)
+                continue
+            if isinstance(node, ast.Import):
+                raise _unsupported(
+                    "Desktop/module imports are not supported in Arduino projects. Use 'from Barmaja_PyArduino import ...'.",
+                    node,
+                )
+            if isinstance(node, (ast.AsyncFunctionDef, ast.ClassDef)):
+                if isinstance(node, ast.ClassDef):
+                    raise _unsupported("Classes are not supported in Barmaja PyArduino V1. Use simple functions instead.", node)
+                raise _unsupported("Async functions are not supported in Barmaja PyArduino V1.", node)
+            if isinstance(node, ast.FunctionDef):
+                if main_loop_seen:
+                    raise _compile_error("Nothing may follow the main top-level 'while True:' loop.", node)
+                self._validate_function(node)
+                continue
+            if isinstance(node, ast.While) and _is_true(node.test):
+                if main_loop_seen:
+                    raise _compile_error("Only one top-level 'while True:' main loop is allowed.", node)
+                if node.orelse:
+                    raise _unsupported("The main 'while True:' loop cannot use an else block.", node)
+                main_loop = node
+                main_loop_seen = True
+                self._validate_block(node.body, context="main", docstring_allowed=False)
+                continue
+            if main_loop_seen:
+                raise _compile_error("Nothing may follow the main top-level 'while True:' loop.", node)
+
+            # Module docstring is accepted only in the actual docstring slot.
+            if is_noop_stmt(node, docstring_allowed=True):
+                continue
+
+            # Recognize hardware-object construction before generic assignment
+            # validation so the object method surface can be checked later.
+            if isinstance(node, ast.Assign) and self._register_hardware_object(node):
+                continue
+
+            self._validate_stmt(node, context="setup", docstring_allowed=False)
+
+        if main_loop is None:
+            raise CompileError("Arduino projects require one top-level 'while True:' main loop.")
+
+        return FrontendModule(
+            tree=tree,
+            api_names=frozenset(self.api_names),
+            source_imports=tuple(self.source_imports),
+            main_loop=main_loop,
+        )
+
+    def _validate_import_from(self, node: ast.ImportFrom) -> None:
+        if node.level != 0 or node.module != "Barmaja_PyArduino":
+            raise _unsupported(
+                "Arduino projects may only import from 'Barmaja_PyArduino'.",
+                node,
+            )
+        for alias in node.names:
+            if alias.asname is not None:
+                raise _unsupported("Import aliases using 'as' are not supported in Barmaja PyArduino V1.", node)
+            if alias.name == "*":
+                self.api_names.update(PUBLIC_API_NAMES)
+                self.source_imports.append("*")
+                continue
+            if alias.name not in PUBLIC_API_NAMES:
+                raise _compile_error(f"'{alias.name}' is not a public Barmaja PyArduino API name.", node)
+            self.api_names.add(alias.name)
+            self.source_imports.append(alias.name)
+
+    def _validate_function(self, fn: ast.FunctionDef) -> None:
+        if fn.decorator_list:
+            raise _unsupported("Decorators are not supported in Barmaja PyArduino V1.", fn)
+        args = fn.args
+        if args.defaults or any(d is not None for d in args.kw_defaults):
+            raise _unsupported("Default function parameters are not supported in Barmaja PyArduino V1.", fn)
+        if args.vararg or args.kwarg or args.kwonlyargs or args.posonlyargs:
+            raise _unsupported("Use simple positional function parameters in Barmaja PyArduino V1.", fn)
+        if fn.returns is not None or any(a.annotation is not None for a in args.args):
+            raise _unsupported("Python type annotations are not supported in Barmaja PyArduino V1 source yet.", fn)
+        self._validate_block(fn.body, context="function", docstring_allowed=True)
+
+    def _register_hardware_object(self, node: ast.Assign) -> bool:
+        if (
+            len(node.targets) == 1
+            and isinstance(node.targets[0], ast.Name)
+            and isinstance(node.value, ast.Call)
+            and isinstance(node.value.func, ast.Name)
+            and node.value.func.id in CONSTRUCTOR_ARITY
+        ):
+            name = node.targets[0].id
+            cls = node.value.func.id
+            self._validate_call(node.value, allow_fstring=False, constructor_allowed=True)
+            if name in self._created_objects:
+                raise _compile_error(
+                    f"'{name}' already holds a hardware object ({self._created_objects[name]}). Create each hardware object once, "
+                    "with its own variable name.",
+                    node,
+                )
+            self._created_objects[name] = cls
+            self.object_classes[name] = cls
+            return True
+        return False
+
+    def _validate_block(self, body: list[ast.stmt], *, context: str, docstring_allowed: bool) -> None:
+        for index, stmt in enumerate(body):
+            self._validate_stmt(stmt, context=context, docstring_allowed=(docstring_allowed and index == 0))
+
+    def _validate_stmt(self, node: ast.stmt, *, context: str, docstring_allowed: bool = False) -> None:
+        if is_noop_stmt(node, docstring_allowed=docstring_allowed):
+            return
+        if _is_docstring_stmt(node):
+            raise _unsupported("Standalone string expressions are not supported here.", node)
+
+        if isinstance(node, ast.Expr):
+            if not isinstance(node.value, ast.Call):
+                raise _unsupported("Only supported function or Arduino method calls may be standalone statements here.", node)
+            self._validate_call(node.value, allow_fstring=False)
+            return
+
+        if isinstance(node, ast.Assign):
+            if len(node.targets) != 1:
+                raise _unsupported("Chained assignment is not supported in Barmaja PyArduino V1.", node)
+            target = node.targets[0]
+            if isinstance(target, ast.Name):
+                self._validate_expr(node.value)
+                return
+            if isinstance(target, ast.Subscript):
+                self._validate_expr(target.value)
+                if isinstance(target.slice, ast.Slice):
+                    raise _unsupported("List slicing is not supported in Barmaja PyArduino V1.", target)
+                self._validate_expr(target.slice)
+                self._validate_expr(node.value)
+                return
+            if context == "setup" and isinstance(target, (ast.Tuple, ast.List)) and isinstance(node.value, (ast.Tuple, ast.List)):
+                # Preserve the existing top-level literal tuple-unpack form only.
+                if len(target.elts) != len(node.value.elts) or not all(isinstance(t, ast.Name) for t in target.elts):
+                    raise _unsupported("Tuple assignment must use the same number of simple variable names and values.", node)
+                for value in node.value.elts:
+                    self._validate_expr(value)
+                    if not _is_literal_scalar(value):
+                        # Python evaluates the whole right side before binding
+                        # (`a, b = b, a` swaps). V1 only lowers literal values here.
+                        raise _unsupported(
+                            "Tuple assignment in Barmaja PyArduino V1 supports literal values only, for example "
+                            "R, G, B = 9, 10, 11. Use one assignment per line (with a temporary variable to swap values).",
+                            node,
+                        )
+                return
+            raise _unsupported("Assignment targets must be simple variable names in Barmaja PyArduino V1.", node)
+
+        if isinstance(node, ast.AnnAssign):
+            raise _unsupported("Annotated assignments such as 'x: int = ...' are not supported in Barmaja PyArduino V1.", node)
+
+        if isinstance(node, ast.AugAssign):
+            if not isinstance(node.target, ast.Name):
+                raise _unsupported("Augmented assignment requires a simple variable name.", node)
+            if not isinstance(node.op, SUPPORTED_AUG_OPS):
+                raise _unsupported("This augmented-assignment operator is not supported in Barmaja PyArduino V1.", node)
+            self._validate_expr(node.value)
+            return
+
+        if isinstance(node, ast.If):
+            self._validate_expr(node.test)
+            self._validate_block(node.body, context=context, docstring_allowed=False)
+            self._validate_block(node.orelse, context=context, docstring_allowed=False)
+            return
+
+        if isinstance(node, ast.While):
+            if node.orelse:
+                raise _unsupported("'while ... else' is not supported in Barmaja PyArduino V1.", node)
+            self._validate_expr(node.test)
+            self._validate_block(node.body, context=context, docstring_allowed=False)
+            return
+
+        if isinstance(node, ast.For):
+            if node.orelse:
+                raise _unsupported("'for ... else' is not supported in Barmaja PyArduino V1.", node)
+            if isinstance(node.iter, ast.Call) and isinstance(node.iter.func, ast.Name) and node.iter.func.id == "range":
+                if not isinstance(node.target, ast.Name):
+                    raise _unsupported("range() loop target must be a simple name.", node)
+                self._validate_range(node.iter, node)
+            elif isinstance(node.iter, ast.Call) and isinstance(node.iter.func, ast.Name) and node.iter.func.id == "enumerate":
+                if not (isinstance(node.target, (ast.Tuple, ast.List)) and len(node.target.elts) == 2 and all(isinstance(x, ast.Name) for x in node.target.elts)):
+                    raise _unsupported("enumerate() loop target must be exactly two simple names: 'for index, value in enumerate(items)'.", node)
+                if not (1 <= len(node.iter.args) <= 2) or not isinstance(node.iter.args[0], ast.Name):
+                    raise _unsupported("enumerate() in V1 requires a fixed-list variable name and optional Int start.", node.iter)
+                self._validate_expr(node.iter.args[0])
+                if len(node.iter.args) == 2:
+                    self._validate_expr(node.iter.args[1])
+            else:
+                if not isinstance(node.target, ast.Name):
+                    raise _unsupported("Fixed-list loop target must be a simple name.", node)
+                if not isinstance(node.iter, ast.Name):
+                    raise _unsupported("Fixed-list iteration in V1 requires a list variable name.", node.iter)
+                self._validate_expr(node.iter)
+            self._validate_block(node.body, context=context, docstring_allowed=False)
+            return
+
+        if isinstance(node, ast.Return):
+            if context != "function":
+                raise _unsupported("return may only be used inside a function.", node)
+            if node.value is not None:
+                self._validate_expr(node.value)
+            return
+
+        if isinstance(node, ast.Global):
+            if context != "function":
+                raise _unsupported("The 'global' statement is supported only inside user functions.", node)
+            if not node.names:
+                raise _unsupported("global requires at least one module variable name.", node)
+            # Binding, existence, ordering and protected-name rules are Phase C.
+            return
+        if isinstance(node, ast.Nonlocal):
+            raise _unsupported("'nonlocal' is not supported because nested functions are outside Barmaja PyArduino V1.", node)
+        if isinstance(node, (ast.Break, ast.Continue)):
+            # Step 6 flow analysis resolves the actual target. In particular,
+            # continue may target the special Arduino main loop, while break
+            # may not terminate that special loop.
+            return
+
+        messages: tuple[tuple[type[ast.AST], str], ...] = (
+            (ast.ClassDef, "Classes are not supported in Barmaja PyArduino V1."),
+            (ast.Try, "try/except/finally is not supported in Barmaja PyArduino V1."),
+            (ast.With, "with-statements are not supported in Barmaja PyArduino V1."),
+            (ast.Raise, "raise is not supported in Barmaja PyArduino V1."),
+            (ast.Assert, "assert is not supported in Barmaja PyArduino V1."),
+            (ast.Delete, "del is not supported in Barmaja PyArduino V1."),
+            (ast.Match, "match/case is not supported in Barmaja PyArduino V1."),
+            (ast.AsyncFor, "async programming is not supported in Barmaja PyArduino V1."),
+            (ast.AsyncWith, "async programming is not supported in Barmaja PyArduino V1."),
+        )
+        for cls, message in messages:
+            if isinstance(node, cls):
+                raise _unsupported(message, node)
+        raise _unsupported("This Python statement is not supported in Barmaja PyArduino V1.", node)
+
+    def _validate_expr(self, node: ast.AST, *, allow_fstring: bool = False) -> None:
+        if isinstance(node, ast.Constant):
+            if node.value is None:
+                raise _unsupported("None is not supported as an Arduino value in Barmaja PyArduino V1.", node)
+            if node.value is Ellipsis:
+                raise _unsupported("Ellipsis (...) is only supported as a no-op statement.", node)
+            if not isinstance(node.value, (bool, int, float, str)):
+                raise _unsupported("This literal value type is not supported in Barmaja PyArduino V1.", node)
+            if isinstance(node.value, str):
+                try:
+                    node.value.encode("utf-8")
+                except UnicodeEncodeError:
+                    raise _unsupported(
+                        "This string contains a character that cannot be sent to the Arduino (an unpaired surrogate such as '\\ud800').",
+                        node,
+                    ) from None
+            return
+        if isinstance(node, ast.Name):
+            return
+        if isinstance(node, ast.JoinedStr):
+            if not allow_fstring:
+                raise _unsupported("f-strings are supported only in print output in Barmaja PyArduino V1.", node)
+            self._validate_fstring(node)
+            return
+        if isinstance(node, ast.FormattedValue):
+            raise _unsupported("Formatted values are supported only as part of a print f-string.", node)
+        if isinstance(node, ast.Call):
+            self._validate_call(node, allow_fstring=False)
+            return
+        if isinstance(node, ast.UnaryOp):
+            if not isinstance(node.op, SUPPORTED_UNARY_OPS):
+                raise _unsupported("This unary operator is not supported in Barmaja PyArduino V1.", node)
+            self._validate_expr(node.operand)
+            return
+        if isinstance(node, ast.BinOp):
+            if not isinstance(node.op, SUPPORTED_BIN_OPS):
+                friendly = "Floor division (//), powers (**), shifts, and bitwise operators are not supported in Barmaja PyArduino V1."
+                raise _unsupported(friendly, node)
+            self._validate_expr(node.left)
+            self._validate_expr(node.right)
+            return
+        if isinstance(node, ast.Compare):
+            for op in node.ops:
+                if not isinstance(op, SUPPORTED_COMPARE_OPS):
+                    raise _unsupported("Only ==, !=, <, <=, >, and >= comparisons are supported in Barmaja PyArduino V1.", node)
+            self._validate_expr(node.left)
+            for comparator in node.comparators:
+                self._validate_expr(comparator)
+            return
+        if isinstance(node, ast.BoolOp):
+            if not isinstance(node.op, (ast.And, ast.Or)):
+                raise _unsupported("This boolean operator is not supported in Barmaja PyArduino V1.", node)
+            for value in node.values:
+                self._validate_expr(value)
+            return
+        if isinstance(node, ast.IfExp):
+            self._validate_expr(node.test)
+            self._validate_expr(node.body)
+            self._validate_expr(node.orelse)
+            return
+
+        if isinstance(node, ast.List):
+            if not node.elts:
+                raise _unsupported("Empty lists are not supported because a fixed element type cannot be inferred.", node)
+            for item in node.elts:
+                self._validate_expr(item)
+            return
+        if isinstance(node, ast.Tuple):
+            raise _unsupported("Tuple values are not supported in Barmaja PyArduino V1 except for supported unpacking/enumerate targets.", node)
+        if isinstance(node, ast.Subscript):
+            if isinstance(node.slice, ast.Slice):
+                raise _unsupported("List slicing is not supported in Barmaja PyArduino V1.", node)
+            if not isinstance(node.value, ast.Name):
+                raise _unsupported("V1 indexing requires a fixed-list variable name.", node)
+            self._validate_expr(node.value)
+            self._validate_expr(node.slice)
+            return
+        if isinstance(node, (ast.Dict, ast.Set)):
+            raise _unsupported("Dictionaries and sets are not supported in Barmaja PyArduino V1.", node)
+        if isinstance(node, (ast.ListComp, ast.SetComp, ast.DictComp, ast.GeneratorExp)):
+            raise _unsupported("Comprehensions and generator expressions are not supported in Barmaja PyArduino V1.", node)
+        if isinstance(node, ast.Lambda):
+            raise _unsupported("lambda functions are not supported in Barmaja PyArduino V1. Use a normal def function.", node)
+        if isinstance(node, ast.NamedExpr):
+            raise _unsupported("The ':=' assignment expression is not supported in Barmaja PyArduino V1.", node)
+        if isinstance(node, (ast.Yield, ast.YieldFrom, ast.Await)):
+            raise _unsupported("Generators and async expressions are not supported in Barmaja PyArduino V1.", node)
+        if isinstance(node, ast.Attribute):
+            raise _unsupported("Attribute access is supported only for registered Arduino method calls.", node)
+        raise _unsupported("This Python expression is not supported in Barmaja PyArduino V1.", node)
+
+    def _validate_fstring(self, node: ast.JoinedStr) -> None:
+        for part in node.values:
+            if isinstance(part, ast.Constant) and isinstance(part.value, str):
+                self._validate_expr(part)  # same literal checks as ordinary strings
+                continue
+            if not isinstance(part, ast.FormattedValue):
+                raise _unsupported("This f-string form is not supported in Barmaja PyArduino V1.", part)
+            if part.conversion != -1:
+                raise _unsupported("f-string conversions such as !r, !s, and !a are not supported in Barmaja PyArduino V1.", part)
+            self._validate_expr(part.value)
+            if part.format_spec is None:
+                continue
+            if not isinstance(part.format_spec, ast.JoinedStr):
+                raise _unsupported("Only fixed '.Nf' f-string precision is supported in Barmaja PyArduino V1.", part)
+            text_parts: list[str] = []
+            for spec_part in part.format_spec.values:
+                if not isinstance(spec_part, ast.Constant) or not isinstance(spec_part.value, str):
+                    raise _unsupported("Dynamic f-string format specifications are not supported in Barmaja PyArduino V1.", part)
+                text_parts.append(spec_part.value)
+            text = "".join(text_parts)
+            if not (len(text) >= 3 and text[0] == "." and text[-1] == "f" and text[1:-1].isdigit()):
+                raise _unsupported("Only fixed '.Nf' f-string precision, such as {value:.1f}, is supported in Barmaja PyArduino V1.", part)
+            if not (text[1:-1].isascii() and 0 <= int(text[1:-1]) <= 6):
+                raise _unsupported("f-string precision '.Nf' supports N from 0 to 6 in Barmaja PyArduino V1, for example {value:.2f}.", part)
+
+    def _validate_call(self, node: ast.Call, *, allow_fstring: bool, constructor_allowed: bool = False) -> None:
+        if any(isinstance(arg, ast.Starred) for arg in node.args):
+            raise _unsupported("Starred call arguments (*args) are not supported in Barmaja PyArduino V1.", node)
+        if node.keywords:
+            raise _unsupported("Keyword arguments are not supported for this call in Barmaja PyArduino V1.", node)
+
+        if isinstance(node.func, ast.Name):
+            name = node.func.id
+            if name in CONSTRUCTOR_ARITY:
+                if not constructor_allowed:
+                    raise _unsupported(f"{name}() hardware objects must be created once as a top-level variable.", node)
+                _check_registered_arities(name, node, HARDWARE_CLASSES[name].constructor_arities)
+            elif name == "print":
+                for arg in node.args:
+                    self._validate_expr(arg, allow_fstring=True)
+                return
+            elif name in CORE_CALL_ARITY:
+                _check_registered_arities(name, node, CORE_FUNCTIONS[name].arities)
+            elif name == "enumerate":
+                raise _unsupported("enumerate() is supported only directly in a fixed-list for-loop.", node)
+            elif name in BUILTIN_CALL_ARITY:
+                _check_arity(name, node, BUILTIN_CALL_ARITY[name])
+                if name in {"len", "sum"} and node.args and not isinstance(node.args[0], ast.Name):
+                    raise _unsupported(f"{name}() in V1 requires a fixed-list variable name.", node)
+            elif name in self.function_names:
+                # Function-call arity is resolved after all definitions are
+                # collected in the symbol/type phases.  The shape is safe here.
+                pass
+            elif name == "range":
+                raise _unsupported("range() is supported only as a for-loop iterator.", node)
+            elif name == "enumerate":
+                raise _unsupported("enumerate() is supported only as a fixed-list for-loop iterator.", node)
+            else:
+                # Step 5 decides whether an ordinary name is a function/API or
+                # undefined.  Keep this node structurally valid for that phase.
+                pass
+            for arg in node.args:
+                self._validate_expr(arg, allow_fstring=allow_fstring)
+            return
+
+        if isinstance(node.func, ast.Attribute) and isinstance(node.func.value, ast.Name):
+            owner = node.func.value.id
+            method = node.func.attr
+            cls = self.object_classes.get(owner)
+            if cls is None and owner in SINGLETONS:
+                cls = owner
+            if cls is None:
+                raise _unsupported("Method calls are supported only on registered Barmaja Arduino objects.", node)
+            methods = METHOD_ARITY[cls]
+            if method not in methods:
+                raise _unsupported(f"{cls}.{method}() is not supported in Barmaja PyArduino V1.", node)
+            _check_registered_arities(
+                f"{owner}.{method}", node,
+                (HARDWARE_CLASSES[cls].methods[method].arities if cls in HARDWARE_CLASSES else SINGLETONS[cls].methods[method].arities),
+            )
+            method_allows_fstring = (
+                (cls == "LiquidCrystal_I2C" and method == "print")
+                or (cls == "Serial" and method in {"print", "println"})
+                or (method in {"print", "println"} and cls in _device_packs.LOADED)
+            )
+            for arg in node.args:
+                self._validate_expr(arg, allow_fstring=method_allows_fstring)
+            return
+
+        raise _unsupported("Only direct function calls and registered Arduino method calls are supported.", node)
+
+    def _validate_range(self, node: ast.AST, owner: ast.For) -> None:
+        if not isinstance(node, ast.Call) or not isinstance(node.func, ast.Name) or node.func.id != "range":
+            raise _unsupported("V1 for-loops use 'for name in range(...)'.", owner)
+        if node.keywords or any(isinstance(arg, ast.Starred) for arg in node.args):
+            raise _unsupported("range() uses positional values only in Barmaja PyArduino V1.", node)
+        if not (1 <= len(node.args) <= 3):
+            raise _compile_error("range() accepts 1 to 3 positional values.", node)
+        for arg in node.args:
+            self._validate_expr(arg)
+        if len(node.args) == 3:
+            step = node.args[2]
+            literal_step = None
+            node_step = step
+            sign = 1
+            while isinstance(node_step, ast.UnaryOp) and isinstance(node_step.op, ast.USub):
+                sign = -sign
+                node_step = node_step.operand
+            if isinstance(node_step, ast.Constant) and isinstance(node_step.value, int) and not isinstance(node_step.value, bool):
+                literal_step = sign * node_step.value
+            if literal_step == 0:
+                raise _compile_error("range() step cannot be zero.", step)
+
+
+def validate_frontend(tree: ast.Module) -> FrontendModule:
+    return FrontendValidator().validate(tree)