Barmaja-PyArduino 2.0.0__py3-none-any.whl

Barmaja_PyArduino/lowering.py

@@ -0,0 +1,596 @@
+from __future__ import annotations
+
+import ast
+
+from .errors import InternalCompilerError
+from .frontend import is_noop_stmt
+from .flow import StorageClass
+from .ir import (
+    IRAugStore,
+    IRBinary,
+    IRBinaryOp,
+    IRBool,
+    IRBoolOp,
+    IRBreak,
+    IRCall,
+    IRCallKind,
+    IRCompareChain,
+    IRCompareOp,
+    IRConditional,
+    IRConstant,
+    IRContinue,
+    IREffect,
+    IRExpr,
+    IRExprStmt,
+    IRFormatString,
+    IRFormattedValue,
+    IRFunction,
+    IRFunctionRef,
+    IRIf,
+    IRIndex,
+    IRIndexStore,
+    IRListLiteral,
+    IRFixedListLoop,
+    IRLoad,
+    IRLoopControlTarget,
+    IRModule,
+    IRObjectDecl,
+    IRPrint,
+    IRRangeLoop,
+    IRReturn,
+    IRStorageDecl,
+    IRStore,
+    IRSymbolRef,
+    IRTempId,
+    IRTempRef,
+    IRUnary,
+    IRUnaryOp,
+    IRWhile,
+    validate_ir,
+)
+from .numeric import NumericAnalysis
+from .source import SourceSpan
+from .symbols import Symbol, SymbolKind
+from .typesys import BOOL, INT, STRING, BarmajaType, TypedModule, TypeKind
+from .api_registry import HARDWARE_CLASSES
+
+
+_BINARY_OPS = {
+    ast.Add: IRBinaryOp.ADD,
+    ast.Sub: IRBinaryOp.SUBTRACT,
+    ast.Mult: IRBinaryOp.MULTIPLY,
+    ast.Div: IRBinaryOp.TRUE_DIVIDE,
+    ast.Mod: IRBinaryOp.MODULO,
+}
+_AUG_OPS = {
+    ast.Add: IRBinaryOp.ADD,
+    ast.Sub: IRBinaryOp.SUBTRACT,
+    ast.Mult: IRBinaryOp.MULTIPLY,
+    ast.Div: IRBinaryOp.TRUE_DIVIDE,
+    ast.Mod: IRBinaryOp.MODULO,
+}
+_COMPARE_OPS = {
+    ast.Eq: IRCompareOp.EQ,
+    ast.NotEq: IRCompareOp.NE,
+    ast.Lt: IRCompareOp.LT,
+    ast.LtE: IRCompareOp.LE,
+    ast.Gt: IRCompareOp.GT,
+    ast.GtE: IRCompareOp.GE,
+}
+
+
+class IRLowerer:
+    """Lower the fully resolved/typed frontend into target-independent IR.
+
+    This phase may inspect Python AST only while lowering. The returned IR owns
+    no AST objects and carries stable SymbolIds, types, spans, and conservative
+    effects. C++ generation remains on the legacy AST path until Step 15.
+    """
+
+    def __init__(self, typed: TypedModule, numeric: NumericAnalysis, source_name: str) -> None:
+        self.typed = typed
+        self.numeric = numeric
+        self.resolved = typed.resolved
+        self.flow = typed.flow
+        self.frontend = self.resolved.frontend
+        self.source_name = source_name
+        self._temp_counter = 0
+        self._temps: list[IRTempRef] = []
+
+    def lower(self) -> IRModule:
+        storages = self._lower_storage_declarations()
+        objects: list[IRObjectDecl] = []
+        setup: list = []
+        functions: list[IRFunction] = []
+
+        main_loop_node = self.frontend.main_loop
+        for stmt in self.frontend.tree.body:
+            if isinstance(stmt, ast.ImportFrom):
+                continue
+            if isinstance(stmt, ast.FunctionDef):
+                functions.append(self._lower_function(stmt))
+                continue
+            if stmt is main_loop_node:
+                continue
+            if is_noop_stmt(stmt, docstring_allowed=True):
+                continue
+            if self._is_hardware_object_assignment(stmt):
+                objects.append(self._lower_object_decl(stmt))
+                continue
+            setup.extend(self._lower_stmt(stmt, in_main=False, nested_loop_depth=0))
+
+        main_loop = tuple(
+            item
+            for stmt in main_loop_node.body
+            for item in self._lower_stmt(stmt, in_main=True, nested_loop_depth=0)
+        )
+
+        module = IRModule(
+            source_name=self.source_name,
+            storages=tuple(storages),
+            objects=tuple(objects),
+            setup=tuple(setup),
+            main_loop=main_loop,
+            functions=tuple(functions),
+            generated_temporaries=tuple(self._temps),
+        )
+        validate_ir(module)
+        return module
+
+    # ---------- declarations ----------
+    def _lower_storage_declarations(self) -> list[IRStorageDecl]:
+        result: list[IRStorageDecl] = []
+        symbols = sorted(
+            (
+                s for s in self.resolved.module_scope.symbols.values()
+                if s.kind == SymbolKind.MODULE
+            ),
+            key=lambda s: s.symbol_id.value,
+        )
+        for symbol in symbols:
+            typ = self.typed.symbol_types.get(symbol.symbol_id)
+            if typ is None or typ.kind == TypeKind.UNKNOWN:
+                raise InternalCompilerError(f"No resolved type is available for module symbol '{symbol.name}'.")
+            facts = self.flow.symbol_facts.get(symbol.symbol_id)
+            if facts is None:
+                raise InternalCompilerError(f"No flow/storage facts are available for module symbol '{symbol.name}'.")
+            result.append(
+                IRStorageDecl(
+                    symbol=self._symbol_ref(symbol),
+                    storage=facts.storage,
+                    initializer=None,
+                    span=self._declaration_span(symbol),
+                )
+            )
+        return result
+
+    def _declaration_span(self, symbol: Symbol) -> SourceSpan | None:
+        if symbol.declaration_line is None:
+            return None
+        return SourceSpan(symbol.declaration_line, 0, symbol.declaration_line, 0)
+
+    def _lower_function(self, node: ast.FunctionDef) -> IRFunction:
+        signature = self.typed.signature_for(node.name)
+        function_symbol = self.resolved.symbol_for_function(node)
+        params = tuple(self._symbol_ref(s) for s in signature.parameters)
+        body = tuple(
+            item
+            for stmt in node.body
+            for item in self._lower_stmt(stmt, in_main=False, nested_loop_depth=0)
+        )
+        return IRFunction(
+            symbol=IRFunctionRef(function_symbol.symbol_id, function_symbol.name, function_symbol.cpp_name),
+            parameters=params,
+            return_type=signature.return_type,
+            body=body,
+            span=self._span(node),
+        )
+
+    @staticmethod
+    def _is_hardware_object_assignment(node: ast.AST) -> bool:
+        return (
+            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 HARDWARE_CLASSES
+        )
+
+    def _lower_object_decl(self, node: ast.Assign) -> IRObjectDecl:
+        target = node.targets[0]
+        assert isinstance(target, ast.Name)
+        call = node.value
+        assert isinstance(call, ast.Call) and isinstance(call.func, ast.Name)
+        symbol = self.resolved.symbol_for_name(target)
+        return IRObjectDecl(
+            symbol=self._symbol_ref(symbol),
+            class_name=call.func.id,
+            args=tuple(self._expr(a) for a in call.args),
+            span=self._span(node),
+        )
+
+    # ---------- statements ----------
+    def _lower_stmt(self, node: ast.stmt, *, in_main: bool, nested_loop_depth: int) -> tuple:
+        if is_noop_stmt(node, docstring_allowed=True) or isinstance(node, ast.Global):
+            return ()
+
+        if isinstance(node, ast.Assign):
+            if len(node.targets) == 1 and isinstance(node.targets[0], ast.Subscript):
+                target = node.targets[0]
+                if not isinstance(target.value, ast.Name):
+                    raise InternalCompilerError("Validated fixed-list store has no list-name target.")
+                return (
+                    IRIndexStore(
+                        span=self._span(node),
+                        collection=self._symbol_ref(self.resolved.symbol_for_name(target.value)),
+                        index=self._expr(target.slice),
+                        value=self._expr(node.value),
+                    ),
+                )
+            if (
+                len(node.targets) == 1
+                and isinstance(node.targets[0], (ast.Tuple, ast.List))
+                and isinstance(node.value, (ast.Tuple, ast.List))
+            ):
+                return tuple(
+                    IRStore(self._span(node), self._symbol_ref(self.resolved.symbol_for_name(t)), self._expr(v))
+                    for t, v in zip(node.targets[0].elts, node.value.elts)
+                    if isinstance(t, ast.Name)
+                )
+            target = node.targets[0]
+            if not isinstance(target, ast.Name):
+                raise InternalCompilerError("Lowering received an unsupported assignment target.")
+            return (
+                IRStore(
+                    span=self._span(node),
+                    target=self._symbol_ref(self.resolved.symbol_for_name(target)),
+                    value=self._expr(node.value),
+                ),
+            )
+
+        if isinstance(node, ast.AugAssign):
+            if not isinstance(node.target, ast.Name):
+                raise InternalCompilerError("Lowering received an unsupported augmented-assignment target.")
+            op = _AUG_OPS.get(type(node.op))
+            if op is None:
+                raise InternalCompilerError("Lowering received an unsupported augmented-assignment operator.")
+            checked = self.numeric.int_expr_needs_runtime_check(node)
+            return (
+                IRAugStore(
+                    span=self._span(node),
+                    target=self._symbol_ref(self.resolved.symbol_for_name(node.target)),
+                    op=op,
+                    value=self._expr(node.value),
+                    checked=checked,
+                ),
+            )
+
+        if isinstance(node, ast.Expr):
+            if isinstance(node.value, ast.Call) and isinstance(node.value.func, ast.Name) and node.value.func.id == "print":
+                return (
+                    IRPrint(
+                        span=self._span(node),
+                        values=tuple(self._expr(arg) for arg in node.value.args),
+                        newline=True,
+                    ),
+                )
+            return (IRExprStmt(self._span(node), self._expr(node.value)),)
+
+        if isinstance(node, ast.If):
+            return (
+                IRIf(
+                    span=self._span(node),
+                    condition=self._expr(node.test),
+                    body=tuple(
+                        item for stmt in node.body
+                        for item in self._lower_stmt(stmt, in_main=in_main, nested_loop_depth=nested_loop_depth)
+                    ),
+                    otherwise=tuple(
+                        item for stmt in node.orelse
+                        for item in self._lower_stmt(stmt, in_main=in_main, nested_loop_depth=nested_loop_depth)
+                    ),
+                ),
+            )
+
+        if isinstance(node, ast.While):
+            return (
+                IRWhile(
+                    span=self._span(node),
+                    condition=self._expr(node.test),
+                    body=tuple(
+                        item for stmt in node.body
+                        for item in self._lower_stmt(stmt, in_main=in_main, nested_loop_depth=nested_loop_depth + 1)
+                    ),
+                ),
+            )
+
+        if isinstance(node, ast.For):
+            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 InternalCompilerError("Validated range loop has no simple target.")
+                args = list(node.iter.args)
+                if len(args) == 1:
+                    start_expr = self._generated_int_constant(0, node.iter)
+                    stop_expr = self._expr(args[0])
+                    step_expr = self._generated_int_constant(1, node.iter)
+                elif len(args) == 2:
+                    start_expr, stop_expr = self._expr(args[0]), self._expr(args[1])
+                    step_expr = self._generated_int_constant(1, node.iter)
+                elif len(args) == 3:
+                    start_expr, stop_expr, step_expr = (self._expr(a) for a in args)
+                else:
+                    raise InternalCompilerError("Validated range() reached lowering with invalid arity.")
+                return (
+                    IRRangeLoop(
+                        span=self._span(node),
+                        target=self._symbol_ref(self.resolved.symbol_for_name(node.target)),
+                        iterator_temp=self._new_temp(INT, "range_iterator", node),
+                        start_temp=self._new_temp(INT, "range_start_once", node.iter),
+                        stop_temp=self._new_temp(INT, "range_stop_once", node.iter),
+                        step_temp=self._new_temp(INT, "range_step_once", node.iter),
+                        start=start_expr,
+                        stop=stop_expr,
+                        step=step_expr,
+                        body=tuple(
+                            item for stmt in node.body
+                            for item in self._lower_stmt(stmt, in_main=in_main, nested_loop_depth=nested_loop_depth + 1)
+                        ),
+                    ),
+                )
+
+            enumerate_mode = isinstance(node.iter, ast.Call) and isinstance(node.iter.func, ast.Name) and node.iter.func.id == "enumerate"
+            collection_node = node.iter.args[0] if enumerate_mode else node.iter
+            if not isinstance(collection_node, ast.Name):
+                raise InternalCompilerError("Validated fixed-list loop has no list-name iterator.")
+            collection_ref = self._symbol_ref(self.resolved.symbol_for_name(collection_node))
+            if enumerate_mode:
+                if not isinstance(node.target, (ast.Tuple, ast.List)) or len(node.target.elts) != 2:
+                    raise InternalCompilerError("Validated enumerate target changed before lowering.")
+                index_node, value_node = node.target.elts
+                if not isinstance(index_node, ast.Name) or not isinstance(value_node, ast.Name):
+                    raise InternalCompilerError("Validated enumerate target is not two simple names.")
+                index_ref = self._symbol_ref(self.resolved.symbol_for_name(index_node))
+                value_ref = self._symbol_ref(self.resolved.symbol_for_name(value_node))
+            else:
+                if not isinstance(node.target, ast.Name):
+                    raise InternalCompilerError("Validated fixed-list loop target is not a simple name.")
+                index_ref = None
+                value_ref = self._symbol_ref(self.resolved.symbol_for_name(node.target))
+            index_start = None
+            index_start_temp = None
+            if enumerate_mode and len(node.iter.args) == 2:
+                index_start = self._expr(node.iter.args[1])
+                index_start_temp = self._new_temp(INT, "enumerate_start_once", node.iter.args[1])
+            return (
+                IRFixedListLoop(
+                    span=self._span(node),
+                    collection=collection_ref,
+                    value_target=value_ref,
+                    index_target=index_ref,
+                    iterator_temp=self._new_temp(INT, "fixed_list_iterator", node),
+                    index_start=index_start,
+                    index_start_temp=index_start_temp,
+                    body=tuple(
+                        item for stmt in node.body
+                        for item in self._lower_stmt(stmt, in_main=in_main, nested_loop_depth=nested_loop_depth + 1)
+                    ),
+                ),
+            )
+
+        if isinstance(node, ast.Break):
+            target = IRLoopControlTarget.NESTED_LOOP
+            if in_main and nested_loop_depth == 0:
+                target = IRLoopControlTarget.MAIN_LOOP
+            return (IRBreak(self._span(node), target),)
+
+        if isinstance(node, ast.Continue):
+            target = IRLoopControlTarget.MAIN_LOOP if in_main and nested_loop_depth == 0 else IRLoopControlTarget.NESTED_LOOP
+            return (IRContinue(self._span(node), target),)
+
+        if isinstance(node, ast.Return):
+            return (IRReturn(self._span(node), None if node.value is None else self._expr(node.value)),)
+
+        raise InternalCompilerError(f"Validated statement {type(node).__name__} has no typed IR lowering path.")
+
+    # ---------- expressions ----------
+    def _expr(self, node: ast.AST) -> IRExpr:
+        typ = self.typed.type_for_expr(node)
+        span = self._span(node)
+
+        if isinstance(node, ast.Constant):
+            if not isinstance(node.value, (bool, int, float, str)):
+                raise InternalCompilerError("Validated constant has no typed IR representation.")
+            return IRConstant(typ, span, frozenset(), node.value)
+
+        if isinstance(node, ast.Name):
+            return IRLoad(typ, span, frozenset(), self._symbol_ref(self.resolved.symbol_for_name(node)))
+
+        if isinstance(node, ast.List):
+            elements = tuple(self._expr(item) for item in node.elts)
+            return IRListLiteral(typ, span, frozenset(self._union_effects(*elements)), elements)
+
+        if isinstance(node, ast.Subscript):
+            collection = self._expr(node.value)
+            index = self._expr(node.slice)
+            effects = self._union_effects(collection, index)
+            if not (isinstance(node.slice, ast.Constant) and isinstance(node.slice.value, int)):
+                effects.add(IREffect.MAY_FAIL)
+            return IRIndex(typ, span, frozenset(effects), collection, index)
+
+        if isinstance(node, ast.UnaryOp):
+            operand = self._expr(node.operand)
+            if isinstance(node.op, ast.USub):
+                op = IRUnaryOp.NEGATE
+            elif isinstance(node.op, ast.Not):
+                op = IRUnaryOp.NOT
+            else:
+                raise InternalCompilerError("Validated unary operator has no typed IR representation.")
+            effects = self._union_effects(operand)
+            if self.numeric.int_expr_needs_runtime_check(node):
+                effects = effects | {IREffect.MAY_FAIL}
+            return IRUnary(typ, span, frozenset(effects), op, operand)
+
+        if isinstance(node, ast.BinOp):
+            left, right = self._expr(node.left), self._expr(node.right)
+            op = _BINARY_OPS.get(type(node.op))
+            if op is None:
+                raise InternalCompilerError("Validated binary operator has no typed IR representation.")
+            checked = self.numeric.int_expr_needs_runtime_check(node)
+            effects = self._union_effects(left, right)
+            if checked or isinstance(node.op, (ast.Div, ast.Mod)):
+                effects.add(IREffect.MAY_FAIL)
+            return IRBinary(typ, span, frozenset(effects), op, left, right, checked)
+
+        if isinstance(node, ast.Compare):
+            operands = (self._expr(node.left),) + tuple(self._expr(c) for c in node.comparators)
+            operators = tuple(_COMPARE_OPS[type(op)] for op in node.ops)
+            effects = self._union_effects(*operands)
+            if any(self.numeric.time_threshold_needs_runtime_check(c) for c in node.comparators):
+                effects.add(IREffect.MAY_FAIL)
+            temps = tuple(self._new_temp(expr.type, "compare_operand_once", source) for expr, source in zip(operands, [node.left, *node.comparators]))
+            return IRCompareChain(typ, span, frozenset(effects), operands, operators, temps)
+
+        if isinstance(node, ast.BoolOp):
+            values = tuple(self._expr(v) for v in node.values)
+            op = IRBoolOp.AND if isinstance(node.op, ast.And) else IRBoolOp.OR
+            return IRBool(typ, span, frozenset(self._union_effects(*values)), op, values)
+
+        if isinstance(node, ast.IfExp):
+            cond, yes, no = self._expr(node.test), self._expr(node.body), self._expr(node.orelse)
+            return IRConditional(typ, span, frozenset(self._union_effects(cond, yes, no)), cond, yes, no)
+
+        if isinstance(node, ast.JoinedStr):
+            parts: list[str | IRFormattedValue] = []
+            child_exprs: list[IRExpr] = []
+            for part in node.values:
+                if isinstance(part, ast.Constant) and isinstance(part.value, str):
+                    parts.append(part.value)
+                    continue
+                if not isinstance(part, ast.FormattedValue):
+                    raise InternalCompilerError("Validated f-string part has no typed IR representation.")
+                value = self._expr(part.value)
+                child_exprs.append(value)
+                parts.append(IRFormattedValue(value, self._fstring_precision(part), self._span(part)))
+            return IRFormatString(STRING, span, frozenset(self._union_effects(*child_exprs)), tuple(parts))
+
+        if isinstance(node, ast.Call):
+            return self._call(node, typ)
+
+        raise InternalCompilerError(f"Validated expression {type(node).__name__} has no typed IR lowering path.")
+
+    def _call(self, node: ast.Call, typ: BarmajaType) -> IRCall:
+        args = tuple(self._expr(a) for a in node.args)
+        effects = self._union_effects(*args)
+        span = self._span(node)
+
+        if isinstance(node.func, ast.Name):
+            name = node.func.id
+            symbol = self.resolved.symbol_for_name(node.func)
+            if symbol.kind == SymbolKind.FUNCTION:
+                effects.add(IREffect.USER_CALL)
+                function_ref = IRFunctionRef(symbol.symbol_id, symbol.name, symbol.cpp_name)
+                return IRCall(
+                    typ, span, frozenset(effects), IRCallKind.USER_FUNCTION, name, args,
+                    function_symbol=function_ref,
+                )
+            if symbol.kind == SymbolKind.BUILTIN:
+                # Checked int conversion and later semantic helpers may fail.
+                if name == "int" or self.numeric.int_expr_needs_runtime_check(node):
+                    effects.add(IREffect.MAY_FAIL)
+                return IRCall(typ, span, frozenset(effects), IRCallKind.BUILTIN, name, args)
+            if symbol.kind == SymbolKind.API:
+                effects.add(IREffect.HARDWARE_IO)
+                if name == "print":
+                    effects.add(IREffect.OUTPUT)
+                if name == "analogWrite" and len(node.args) > 1 and self.numeric.pwm_arg_needs_runtime_check(node.args[1]):
+                    effects.add(IREffect.MAY_FAIL)
+                return IRCall(typ, span, frozenset(effects), IRCallKind.API_FUNCTION, name, args)
+            raise InternalCompilerError(f"Resolved direct call '{name}' has no IR call category.")
+
+        if isinstance(node.func, ast.Attribute) and isinstance(node.func.value, ast.Name):
+            owner_node = node.func.value
+            owner_name = owner_node.id
+            owner_symbol = self.resolved.symbol_for_name(owner_node)
+            owner_ref = None
+            kind = IRCallKind.SINGLETON_METHOD
+            if owner_symbol.kind == SymbolKind.HARDWARE:
+                owner_ref = self._symbol_ref(owner_symbol)
+                kind = IRCallKind.OBJECT_METHOD
+            effects.add(IREffect.HARDWARE_IO)
+            if (owner_name == "Serial" and node.func.attr in {"print", "println"}) or node.func.attr == "print":
+                effects.add(IREffect.OUTPUT)
+            return IRCall(
+                typ, span, frozenset(effects), kind,
+                f"{owner_name}.{node.func.attr}", args,
+                owner_symbol=owner_ref,
+                owner_name=owner_name,
+                method_name=node.func.attr,
+            )
+
+        raise InternalCompilerError("Validated call has no typed IR lowering path.")
+
+    # ---------- helpers ----------
+    def _symbol_ref(self, symbol: Symbol) -> IRSymbolRef:
+        typ = self.typed.symbol_types.get(symbol.symbol_id)
+        if typ is None:
+            # Constants/API singleton spellings are represented as API value
+            # loads when used as values. Their language value type is Int.
+            if symbol.kind == SymbolKind.API and symbol.name in {
+                "HIGH", "LOW", "INPUT", "OUTPUT", "INPUT_PULLUP",
+                "A0", "A1", "A2", "A3", "A4", "A5",
+                "DHT11", "DHT22", "CM", "INC",
+            }:
+                typ = INT
+            else:
+                raise InternalCompilerError(f"No resolved type is available for symbol '{symbol.name}'.")
+        if typ.kind == TypeKind.UNKNOWN:
+            raise InternalCompilerError(f"Symbol '{symbol.name}' reached IR lowering with Unknown type.")
+        return IRSymbolRef(symbol.symbol_id, symbol.name, symbol.cpp_name, symbol.kind, typ)
+
+    def _new_temp(self, typ: BarmajaType, purpose: str, owner: ast.AST) -> IRTempRef:
+        self._temp_counter += 1
+        temp = IRTempRef(IRTempId(self._temp_counter), f"_bj_t{self._temp_counter:04d}", typ, purpose, self._span(owner))
+        self._temps.append(temp)
+        return temp
+
+    def _generated_int_constant(self, value: int, owner: ast.AST) -> IRConstant:
+        return IRConstant(INT, self._span(owner), frozenset(), value)
+
+    @staticmethod
+    def _union_effects(*expressions: IRExpr) -> set[IREffect]:
+        result: set[IREffect] = set()
+        for expr in expressions:
+            result.update(expr.effects)
+        return result
+
+    @staticmethod
+    def _span(node: ast.AST) -> SourceSpan | None:
+        line = getattr(node, "lineno", None)
+        column = getattr(node, "col_offset", None)
+        if line is None or column is None:
+            return None
+        return SourceSpan(
+            line,
+            column,
+            getattr(node, "end_lineno", None) or line,
+            getattr(node, "end_col_offset", None) if getattr(node, "end_col_offset", None) is not None else column,
+        )
+
+    @staticmethod
+    def _fstring_precision(node: ast.FormattedValue) -> int | None:
+        if node.format_spec is None:
+            return None
+        if not isinstance(node.format_spec, ast.JoinedStr):
+            raise InternalCompilerError("Validated f-string format has no typed IR representation.")
+        text = "".join(
+            part.value for part in node.format_spec.values
+            if isinstance(part, ast.Constant) and isinstance(part.value, str)
+        )
+        if len(text) >= 3 and text.startswith(".") and text.endswith("f") and text[1:-1].isdigit():
+            return int(text[1:-1])
+        raise InternalCompilerError("Validated f-string precision has no typed IR representation.")
+
+
+def lower_to_ir(typed: TypedModule, numeric: NumericAnalysis, source_name: str = "<student.py>") -> IRModule:
+    return IRLowerer(typed, numeric, source_name).lower()