Barmaja-PyArduino 2.0.0__py3-none-any.whl

Barmaja_PyArduino/flow.py

@@ -0,0 +1,754 @@
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass, field
+from enum import Enum
+
+from .errors import CompileError, NameResolutionError, UnsupportedFeatureError
+from .frontend import is_noop_stmt
+from .symbols import ResolvedModule, Symbol, SymbolId, SymbolKind
+
+
+class StorageClass(Enum):
+    MODULE_CONSTANT = "module_constant"
+    PERSISTENT_MODULE = "persistent_module"
+    SETUP_LOCAL = "setup_local"
+    LOOP_TEMPORARY = "loop_temporary"
+    HARDWARE_PERSISTENT = "hardware_persistent"
+    FUNCTION_LOCAL = "function_local"
+    PARAMETER = "parameter"
+
+
+@dataclass(frozen=True)
+class CFGNode:
+    node_id: int
+    kind: str
+    line: int | None
+    successors: tuple[int, ...] = ()
+
+
+@dataclass(frozen=True)
+class ControlFlowGraph:
+    name: str
+    entry_id: int
+    exit_id: int
+    nodes: tuple[CFGNode, ...]
+
+
+@dataclass(frozen=True)
+class SymbolFlowFacts:
+    symbol: Symbol
+    storage: StorageClass
+    read_regions: frozenset[str] = frozenset()
+    write_regions: frozenset[str] = frozenset()
+    assignment_count: int = 0
+    loop_reads_before_write: bool = False
+
+
+@dataclass(frozen=True)
+class FunctionFlowFacts:
+    name: str
+    definitely_assigned_at_exit: frozenset[SymbolId]
+    has_value_return: bool
+    has_bare_return: bool
+    can_fall_through: bool
+
+
+@dataclass(frozen=True)
+class FlowAnalyzedModule:
+    resolved: ResolvedModule
+    setup_graph: ControlFlowGraph
+    loop_graph: ControlFlowGraph
+    function_graphs: dict[str, ControlFlowGraph]
+    symbol_facts: dict[SymbolId, SymbolFlowFacts]
+    function_facts: dict[str, FunctionFlowFacts]
+    setup_exit_assigned: frozenset[SymbolId]
+    loop_exit_assigned: frozenset[SymbolId]
+
+    def facts_for(self, symbol: Symbol) -> SymbolFlowFacts:
+        return self.symbol_facts[symbol.symbol_id]
+
+    def storage_for(self, symbol: Symbol) -> StorageClass:
+        return self.facts_for(symbol).storage
+
+
+@dataclass
+class _Outcome:
+    normal: set[SymbolId] | None
+    breaks: list[set[SymbolId]] = field(default_factory=list)
+    continues: list[set[SymbolId]] = field(default_factory=list)
+    value_returns: int = 0
+    bare_returns: int = 0
+
+    def merge_transfers(self, other: "_Outcome") -> None:
+        self.breaks.extend(other.breaks)
+        self.continues.extend(other.continues)
+        self.value_returns += other.value_returns
+        self.bare_returns += other.bare_returns
+
+
+class _CFGBuilder:
+    """Small explicit CFG snapshot for diagnostics/tests.
+
+    Definite-assignment itself is a structured fixed-point-safe analysis below;
+    this graph records the same region's control structure without pretending
+    that C++ scope is Python scope.
+    """
+
+    def __init__(self, name: str) -> None:
+        self.name = name
+        self._next = 0
+        self._nodes: dict[int, tuple[str, int | None, list[int]]] = {}
+        self.entry = self._new("entry", None)
+        self.exit = self._new("exit", None)
+
+    def _new(self, kind: str, line: int | None) -> int:
+        nid = self._next
+        self._next += 1
+        self._nodes[nid] = (kind, line, [])
+        return nid
+
+    def _edge(self, source: int, target: int) -> None:
+        succ = self._nodes[source][2]
+        if target not in succ:
+            succ.append(target)
+
+    def build(self, body: list[ast.stmt]) -> ControlFlowGraph:
+        tails = [self.entry]
+        tails = self._block(body, tails)
+        for tail in tails:
+            self._edge(tail, self.exit)
+        nodes = tuple(
+            CFGNode(nid, kind, line, tuple(succ))
+            for nid, (kind, line, succ) in sorted(self._nodes.items())
+        )
+        return ControlFlowGraph(self.name, self.entry, self.exit, nodes)
+
+    def _block(self, body: list[ast.stmt], incoming: list[int]) -> list[int]:
+        tails = incoming
+        for stmt in body:
+            if not tails:
+                break
+            nid = self._new(type(stmt).__name__, getattr(stmt, "lineno", None))
+            for tail in tails:
+                self._edge(tail, nid)
+            if isinstance(stmt, ast.If):
+                yes = self._block(stmt.body, [nid]) or [nid]
+                no = self._block(stmt.orelse, [nid]) if stmt.orelse else [nid]
+                tails = yes + no
+            elif isinstance(stmt, (ast.While, ast.For)):
+                body_tails = self._block(stmt.body, [nid])
+                for tail in body_tails:
+                    self._edge(tail, nid)
+                tails = [nid]
+            elif isinstance(stmt, (ast.Return, ast.Break, ast.Continue)):
+                tails = []
+            else:
+                tails = [nid]
+        return tails
+
+
+class FlowAnalyzer:
+    def __init__(self, resolved: ResolvedModule) -> None:
+        self.resolved = resolved
+        self.frontend = resolved.frontend
+        self._reads: dict[SymbolId, set[str]] = {}
+        self._writes: dict[SymbolId, set[str]] = {}
+        self._assign_count: dict[SymbolId, int] = {}
+        self._loop_reads_before_write: set[SymbolId] = set()
+
+    def analyze(self) -> FlowAnalyzedModule:
+        setup_body = self._setup_runtime_body()
+        loop_body = list(self.frontend.main_loop.body)
+
+        setup_graph = _CFGBuilder("setup").build(setup_body)
+        loop_graph = _CFGBuilder("main_loop").build(loop_body)
+        function_graphs = {
+            fn.name: _CFGBuilder(f"function:{fn.name}").build(fn.body)
+            for fn in self.frontend.tree.body if isinstance(fn, ast.FunctionDef)
+        }
+
+        # Module execution begins with no user variable value available. API,
+        # builtins and function definitions are compile-time bindings, not data
+        # values tracked in the definite-assignment set.
+        setup_out = self._analyze_block(setup_body, set(), "setup", loop_stack=[])
+        if setup_out.normal is None:
+            # Setup-time return is structurally impossible; an infinite setup
+            # loop is valid Python but leaves no path to Arduino loop().
+            setup_exit: set[SymbolId] = set()
+        else:
+            setup_exit = set(setup_out.normal)
+
+        # The special top-level while True is represented by Arduino loop().
+        # Its first logical iteration starts with values established by setup.
+        loop_out = self._analyze_block(loop_body, set(setup_exit), "loop", loop_stack=["main"])
+        loop_exit = set(loop_out.normal or setup_exit)
+        if loop_out.breaks:
+            # Flow analysis should already reject a break targeting main.
+            raise CompileError("The main Arduino loop cannot be terminated with break.")
+
+        function_facts: dict[str, FunctionFlowFacts] = {}
+        for fn in self.frontend.tree.body:
+            if not isinstance(fn, ast.FunctionDef):
+                continue
+            scope = self.resolved.function_scopes[fn.name]
+            initial = {
+                sym.symbol_id for sym in scope.symbols.values()
+                if sym.kind == SymbolKind.PARAMETER
+            }
+            out = self._analyze_block(fn.body, initial, f"function:{fn.name}", loop_stack=[])
+            has_value = out.value_returns > 0
+            has_bare = out.bare_returns > 0
+            can_fall = out.normal is not None
+            if has_value and has_bare:
+                raise CompileError(
+                    f"Function '{fn.name}' mixes 'return value' and bare 'return'. Use one return style.",
+                    fn.lineno,
+                )
+            if has_value and can_fall:
+                raise CompileError(
+                    f"Function '{fn.name}' returns a value on some paths but can finish without returning a value.",
+                    fn.lineno,
+                )
+            function_facts[fn.name] = FunctionFlowFacts(
+                fn.name,
+                frozenset(out.normal or set()),
+                has_value,
+                has_bare,
+                can_fall,
+            )
+
+        self._mark_loop_reads_before_write(loop_body)
+        facts = self._classify_storage(setup_exit)
+
+        return FlowAnalyzedModule(
+            resolved=self.resolved,
+            setup_graph=setup_graph,
+            loop_graph=loop_graph,
+            function_graphs=function_graphs,
+            symbol_facts=facts,
+            function_facts=function_facts,
+            setup_exit_assigned=frozenset(setup_exit),
+            loop_exit_assigned=frozenset(loop_exit),
+        )
+
+    # ---------- source regions ----------
+    def _setup_runtime_body(self) -> list[ast.stmt]:
+        body: list[ast.stmt] = []
+        for stmt in self.frontend.tree.body:
+            if isinstance(stmt, (ast.ImportFrom, ast.FunctionDef)):
+                continue
+            if stmt is self.frontend.main_loop:
+                break
+            if is_noop_stmt(stmt, docstring_allowed=True):
+                continue
+            body.append(stmt)
+        return body
+
+    # ---------- definite assignment ----------
+    def _analyze_block(
+        self,
+        body: list[ast.stmt],
+        assigned: set[SymbolId],
+        region: str,
+        *,
+        loop_stack: list[str],
+    ) -> _Outcome:
+        normal: set[SymbolId] | None = set(assigned)
+        result = _Outcome(normal)
+        for stmt in body:
+            if normal is None:
+                # Statements after return/break/continue/infinite loops never run,
+                # and Python accepts them.  They are still emitted as C++, so their
+                # variable accesses must still decide storage (otherwise a variable
+                # used only there gets no declaration in the right C++ scope).
+                self._record_unreachable_accesses(stmt, region)
+                continue
+            out = self._analyze_stmt(stmt, normal, region, loop_stack=loop_stack)
+            result.breaks.extend(out.breaks)
+            result.continues.extend(out.continues)
+            result.value_returns += out.value_returns
+            result.bare_returns += out.bare_returns
+            normal = out.normal
+        result.normal = normal
+        return result
+
+    def _analyze_stmt(
+        self,
+        stmt: ast.stmt,
+        assigned: set[SymbolId],
+        region: str,
+        *,
+        loop_stack: list[str],
+    ) -> _Outcome:
+        if is_noop_stmt(stmt, docstring_allowed=True) or isinstance(stmt, ast.Global):
+            return _Outcome(set(assigned))
+
+        if isinstance(stmt, ast.Expr):
+            self._check_expr(stmt.value, assigned, region)
+            return _Outcome(set(assigned))
+
+        if isinstance(stmt, ast.Assign):
+            self._check_expr(stmt.value, assigned, region)
+            out = set(assigned)
+            for target in stmt.targets:
+                if isinstance(target, ast.Subscript):
+                    # Element mutation reads the existing list and index; it
+                    # does not create/rebind the list variable itself.
+                    self._check_expr(target.value, assigned, region)
+                    self._check_expr(target.slice, assigned, region)
+                    if isinstance(target.value, ast.Name):
+                        symbol = self.resolved.symbol_for_name(target.value)
+                        self._record_write(symbol, region)
+                        self._assign_count[symbol.symbol_id] = self._assign_count.get(symbol.symbol_id, 0) + 1
+                    continue
+                self._assign_target(target, out, region)
+            return _Outcome(out)
+
+        if isinstance(stmt, ast.AugAssign):
+            self._require_target_assigned(stmt.target, assigned, region)
+            self._check_expr(stmt.value, assigned, region)
+            out = set(assigned)
+            self._assign_target(stmt.target, out, region)
+            return _Outcome(out)
+
+        if isinstance(stmt, ast.If):
+            self._check_expr(stmt.test, assigned, region)
+            yes = self._analyze_block(stmt.body, set(assigned), region, loop_stack=loop_stack)
+            no = self._analyze_block(stmt.orelse, set(assigned), region, loop_stack=loop_stack) if stmt.orelse else _Outcome(set(assigned))
+            normals = [x.normal for x in (yes, no) if x.normal is not None]
+            normal = self._intersection(normals) if normals else None
+            out = _Outcome(normal)
+            out.merge_transfers(yes)
+            out.merge_transfers(no)
+            return out
+
+        if isinstance(stmt, ast.For):
+            self._check_expr(stmt.iter, assigned, region)
+            targets = self._symbols_for_loop_target(stmt.target)
+            body_in = set(assigned)
+            for target_symbol in targets:
+                body_in.add(target_symbol.symbol_id)
+                self._record_write(target_symbol, region)
+            body = self._analyze_block(stmt.body, body_in, region, loop_stack=[*loop_stack, "nested"])
+            guaranteed_nonempty = self._for_iter_is_statically_nonempty(stmt.iter)
+            normal = set(assigned)
+            if guaranteed_nonempty:
+                normal.update(sym.symbol_id for sym in targets)
+            out = _Outcome(normal)
+            out.value_returns = body.value_returns
+            out.bare_returns = body.bare_returns
+            return out
+
+        if isinstance(stmt, ast.While):
+            self._check_expr(stmt.test, assigned, region)
+            body = self._analyze_block(stmt.body, set(assigned), region, loop_stack=[*loop_stack, "nested"])
+            if self._is_true(stmt.test):
+                # A normal infinite while has no fallthrough unless a nested
+                # break targets it. break states are the only normal exits.
+                normal = self._intersection(body.breaks) if body.breaks else None
+            else:
+                normal = set(assigned)
+                if body.breaks:
+                    normal &= self._intersection(body.breaks)
+            out = _Outcome(normal)
+            out.value_returns = body.value_returns
+            out.bare_returns = body.bare_returns
+            return out
+
+        if isinstance(stmt, ast.Break):
+            if not loop_stack:
+                raise CompileError("break may only be used inside a loop.", stmt.lineno)
+            if loop_stack[-1] == "main":
+                raise UnsupportedFeatureError(
+                    "break cannot target the top-level Arduino 'while True:' loop because Arduino loop() is called repeatedly.",
+                    line=stmt.lineno,
+                    column=(getattr(stmt, "col_offset", 0) + 1),
+                )
+            return _Outcome(None, breaks=[set(assigned)])
+
+        if isinstance(stmt, ast.Continue):
+            if not loop_stack:
+                raise CompileError("continue may only be used inside a loop.", stmt.lineno)
+            return _Outcome(None, continues=[set(assigned)])
+
+        if isinstance(stmt, ast.Return):
+            if stmt.value is not None:
+                self._check_expr(stmt.value, assigned, region)
+                return _Outcome(None, value_returns=1)
+            return _Outcome(None, bare_returns=1)
+
+        raise CompileError(
+            f"Control-flow analysis does not support '{type(stmt).__name__}' yet.",
+            getattr(stmt, "lineno", None),
+        )
+
+    def _check_expr(self, expr: ast.AST, assigned: set[SymbolId], region: str) -> None:
+        for node in ast.walk(expr):
+            if not isinstance(node, ast.Name) or not isinstance(node.ctx, ast.Load):
+                continue
+            try:
+                symbol = self.resolved.symbol_for_name(node)
+            except KeyError:
+                continue
+            self._record_read(symbol, region)
+            if symbol.kind in {SymbolKind.API, SymbolKind.BUILTIN, SymbolKind.FUNCTION}:
+                continue
+            if symbol.kind == SymbolKind.PARAMETER:
+                if symbol.symbol_id not in assigned:
+                    self._unbound(symbol, node, local=True)
+                continue
+            if symbol.kind == SymbolKind.LOCAL:
+                if symbol.symbol_id not in assigned:
+                    self._unbound(symbol, node, local=True)
+                continue
+            # Module values are tracked during setup/main flow. Inside a user
+            # function, Step-5 call-order checks establish module availability;
+            # function-local assignment remains the concern here.
+            if region.startswith("function:"):
+                continue
+            if symbol.symbol_id not in assigned:
+                self._unbound(symbol, node, local=False)
+
+    def _require_target_assigned(self, target: ast.AST, assigned: set[SymbolId], region: str) -> None:
+        if isinstance(target, ast.Name):
+            symbol = self.resolved.symbol_for_name(target)
+            self._record_read(symbol, region)
+            if region.startswith("function:") and symbol.scope_name == "<module>":
+                return
+            if symbol.symbol_id not in assigned and symbol.kind not in {SymbolKind.API, SymbolKind.BUILTIN, SymbolKind.FUNCTION}:
+                self._unbound(symbol, target, local=symbol.kind in {SymbolKind.LOCAL, SymbolKind.PARAMETER})
+
+    def _assign_target(self, target: ast.AST, assigned: set[SymbolId], region: str) -> None:
+        if isinstance(target, ast.Name):
+            symbol = self.resolved.symbol_for_name(target)
+            assigned.add(symbol.symbol_id)
+            self._record_write(symbol, region)
+            return
+        if isinstance(target, (ast.Tuple, ast.List)):
+            for elt in target.elts:
+                self._assign_target(elt, assigned, region)
+
+    def _symbols_for_loop_target(self, target: ast.AST) -> list[Symbol]:
+        if isinstance(target, ast.Name):
+            return [self.resolved.symbol_for_name(target)]
+        if isinstance(target, (ast.Tuple, ast.List)):
+            result: list[Symbol] = []
+            for elt in target.elts:
+                if not isinstance(elt, ast.Name):
+                    raise CompileError("Loop target must use simple names.", getattr(target, "lineno", None))
+                result.append(self.resolved.symbol_for_name(elt))
+            return result
+        raise CompileError("Loop target must use simple names.", getattr(target, "lineno", None))
+
+    def _unbound(self, symbol: Symbol, node: ast.AST, *, local: bool) -> None:
+        wording = "local variable" if local else "variable"
+        raise NameResolutionError(
+            f"Possibly unbound {wording} '{symbol.name}' may be read before it has a value.",
+            line=getattr(node, "lineno", None),
+            column=(getattr(node, "col_offset", 0) + 1),
+            end_line=getattr(node, "end_lineno", None),
+            end_column=getattr(node, "end_col_offset", None),
+        )
+
+    @staticmethod
+    def _intersection(sets: list[set[SymbolId]]) -> set[SymbolId]:
+        if not sets:
+            return set()
+        out = set(sets[0])
+        for item in sets[1:]:
+            out &= item
+        return out
+
+    def _record_unreachable_accesses(self, stmt: ast.stmt, region: str) -> None:
+        for node in ast.walk(stmt):
+            if isinstance(node, ast.Name):
+                try:
+                    symbol = self.resolved.symbol_for_name(node)
+                except KeyError:
+                    continue
+                if isinstance(node.ctx, ast.Store):
+                    self._record_write(symbol, region)
+                else:
+                    self._record_read(symbol, region)
+            elif isinstance(node, ast.AugAssign) and isinstance(node.target, ast.Name):
+                try:
+                    self._record_read(self.resolved.symbol_for_name(node.target), region)
+                except KeyError:
+                    pass
+
+    # ---------- access facts / storage ----------
+    def _record_read(self, symbol: Symbol, region: str) -> None:
+        if symbol.is_user_symbol:
+            self._reads.setdefault(symbol.symbol_id, set()).add(region)
+
+    def _record_write(self, symbol: Symbol, region: str) -> None:
+        if symbol.is_user_symbol:
+            self._writes.setdefault(symbol.symbol_id, set()).add(region)
+            self._assign_count[symbol.symbol_id] = self._assign_count.get(symbol.symbol_id, 0) + 1
+
+    def _mark_loop_reads_before_write(self, body: list[ast.stmt]) -> None:
+        # Per-symbol definite assignment from the start of a logical main-loop
+        # iteration, intentionally ignoring setup values. A read before a
+        # current-iteration write means the previous value can be observed.
+        for symbol in self.resolved.module_scope.symbols.values():
+            if symbol.kind not in {SymbolKind.MODULE, SymbolKind.HARDWARE}:
+                continue
+            if symbol.kind == SymbolKind.HARDWARE:
+                continue
+            if self._reads_before_write_block(body, symbol.symbol_id, False)[1]:
+                self._loop_reads_before_write.add(symbol.symbol_id)
+
+    def _reads_before_write_block(self, body: list[ast.stmt], sid: SymbolId, assigned: bool) -> tuple[bool, bool]:
+        read_before = False
+        current = assigned
+        for stmt in body:
+            if isinstance(stmt, ast.Assign):
+                if self._expr_reads_symbol(stmt.value, sid) and not current:
+                    read_before = True
+                if any(self._target_is_symbol(t, sid) for t in stmt.targets):
+                    current = True
+            elif isinstance(stmt, ast.AugAssign):
+                if self._target_is_symbol(stmt.target, sid) and not current:
+                    read_before = True
+                if self._expr_reads_symbol(stmt.value, sid) and not current:
+                    read_before = True
+                if self._target_is_symbol(stmt.target, sid):
+                    current = True
+            elif isinstance(stmt, ast.If):
+                if self._expr_reads_symbol(stmt.test, sid) and not current:
+                    read_before = True
+                y_assigned, y_read = self._reads_before_write_block(stmt.body, sid, current)
+                n_assigned, n_read = self._reads_before_write_block(stmt.orelse, sid, current) if stmt.orelse else (current, False)
+                read_before |= y_read or n_read
+                current = y_assigned and n_assigned
+            elif isinstance(stmt, ast.For):
+                if self._expr_reads_symbol(stmt.iter, sid) and not current:
+                    read_before = True
+                target_here = self._target_is_symbol(stmt.target, sid)
+                body_assigned, body_read = self._reads_before_write_block(stmt.body, sid, current or target_here)
+                read_before |= body_read
+                if target_here and self._range_is_statically_nonempty(stmt.iter):
+                    current = True
+            elif isinstance(stmt, ast.While):
+                if self._expr_reads_symbol(stmt.test, sid) and not current:
+                    read_before = True
+                _, body_read = self._reads_before_write_block(stmt.body, sid, current)
+                read_before |= body_read
+            else:
+                for node in ast.walk(stmt):
+                    if isinstance(node, ast.Name) and isinstance(node.ctx, ast.Load):
+                        try:
+                            sym = self.resolved.symbol_for_name(node)
+                        except KeyError:
+                            continue
+                        if sym.symbol_id == sid and not current:
+                            read_before = True
+        return current, read_before
+
+    def _expr_reads_symbol(self, expr: ast.AST, sid: SymbolId) -> bool:
+        for node in ast.walk(expr):
+            if isinstance(node, ast.Name) and isinstance(node.ctx, ast.Load):
+                try:
+                    if self.resolved.symbol_for_name(node).symbol_id == sid:
+                        return True
+                except KeyError:
+                    pass
+        return False
+
+    def _target_is_symbol(self, target: ast.AST, sid: SymbolId) -> bool:
+        if isinstance(target, ast.Name):
+            try:
+                return self.resolved.symbol_for_name(target).symbol_id == sid
+            except KeyError:
+                return False
+        if isinstance(target, (ast.Tuple, ast.List)):
+            return any(self._target_is_symbol(x, sid) for x in target.elts)
+        return False
+
+    def _classify_storage(self, setup_exit: set[SymbolId]) -> dict[SymbolId, SymbolFlowFacts]:
+        facts: dict[SymbolId, SymbolFlowFacts] = {}
+        assignment_sites = self._module_assignment_sites()
+        function_regions = {
+            region for regions in (*self._reads.values(), *self._writes.values())
+            for region in regions if region.startswith("function:")
+        }
+        _ = function_regions  # documentary: function access is handled per-symbol below.
+
+        for symbol in self.resolved.module_scope.symbols.values():
+            if not symbol.is_user_symbol:
+                continue
+            reads = frozenset(self._reads.get(symbol.symbol_id, set()))
+            writes = frozenset(self._writes.get(symbol.symbol_id, set()))
+            count = self._assign_count.get(symbol.symbol_id, 0)
+            rbw = symbol.symbol_id in self._loop_reads_before_write
+
+            if symbol.kind == SymbolKind.FUNCTION:
+                # Functions have code identity, not variable storage.
+                continue
+            if symbol.kind == SymbolKind.HARDWARE:
+                storage = StorageClass.HARDWARE_PERSISTENT
+            else:
+                sites = assignment_sites.get(symbol.symbol_id, [])
+                one_pure = len(sites) == 1 and self._is_pure_compile_time_expr(sites[0][1])
+                mutated_in_function = any(r.startswith("function:") for r in writes)
+                if one_pure and not mutated_in_function:
+                    storage = StorageClass.MODULE_CONSTANT
+                elif any(r.startswith("function:") for r in reads | writes):
+                    storage = StorageClass.PERSISTENT_MODULE
+                elif "loop" in reads or "loop" in writes:
+                    if "setup" in writes or rbw:
+                        storage = StorageClass.PERSISTENT_MODULE
+                    else:
+                        storage = StorageClass.LOOP_TEMPORARY
+                else:
+                    storage = StorageClass.SETUP_LOCAL
+
+            facts[symbol.symbol_id] = SymbolFlowFacts(
+                symbol=symbol,
+                storage=storage,
+                read_regions=reads,
+                write_regions=writes,
+                assignment_count=count,
+                loop_reads_before_write=rbw,
+            )
+
+        for scope in self.resolved.function_scopes.values():
+            for symbol in scope.symbols.values():
+                storage = StorageClass.PARAMETER if symbol.kind == SymbolKind.PARAMETER else StorageClass.FUNCTION_LOCAL
+                facts[symbol.symbol_id] = SymbolFlowFacts(
+                    symbol=symbol,
+                    storage=storage,
+                    read_regions=frozenset(self._reads.get(symbol.symbol_id, set())),
+                    write_regions=frozenset(self._writes.get(symbol.symbol_id, set())),
+                    assignment_count=self._assign_count.get(symbol.symbol_id, 0),
+                )
+        return facts
+
+    def _module_assignment_sites(self) -> dict[SymbolId, list[tuple[ast.AST, ast.AST]]]:
+        sites: dict[SymbolId, list[tuple[ast.AST, ast.AST]]] = {}
+        analyzer = self
+
+        class Visitor(ast.NodeVisitor):
+            def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
+                return
+
+            def visit_Assign(self, node: ast.Assign) -> None:
+                for target in node.targets:
+                    if isinstance(target, ast.Subscript) and isinstance(target.value, ast.Name):
+                        try:
+                            sym = analyzer.resolved.symbol_for_name(target.value)
+                        except KeyError:
+                            sym = None
+                        if sym is not None and sym.scope_name == "<module>":
+                            sites.setdefault(sym.symbol_id, []).append((target.value, node.value))
+                        self.visit(target.slice)
+                        continue
+                    for t, value in analyzer._target_value_pairs(target, node.value):
+                        if not isinstance(t, ast.Name):
+                            continue
+                        try:
+                            sym = analyzer.resolved.symbol_for_name(t)
+                        except KeyError:
+                            continue
+                        if sym.scope_name == "<module>":
+                            sites.setdefault(sym.symbol_id, []).append((t, value))
+                self.generic_visit(node.value)
+
+            def visit_AugAssign(self, node: ast.AugAssign) -> None:
+                if isinstance(node.target, ast.Name):
+                    try:
+                        sym = analyzer.resolved.symbol_for_name(node.target)
+                    except KeyError:
+                        sym = None
+                    if sym is not None and sym.scope_name == "<module>":
+                        sites.setdefault(sym.symbol_id, []).append((node.target, node.value))
+                self.generic_visit(node.value)
+
+            def visit_For(self, node: ast.For) -> None:
+                # Every loop target (including enumerate tuple targets) is a
+                # write site; missing one would misclassify the name as a constant.
+                targets = [node.target] if isinstance(node.target, ast.Name) else [
+                    elt for elt in getattr(node.target, "elts", ()) if isinstance(elt, ast.Name)
+                ]
+                for target in targets:
+                    try:
+                        sym = analyzer.resolved.symbol_for_name(target)
+                    except KeyError:
+                        sym = None
+                    if sym is not None and sym.scope_name == "<module>":
+                        sites.setdefault(sym.symbol_id, []).append((target, node.iter))
+                self.visit(node.iter)
+                for child in node.body:
+                    self.visit(child)
+
+        Visitor().visit(self.frontend.tree)
+        return sites
+
+    @staticmethod
+    def _target_value_pairs(target: ast.AST, value: ast.AST) -> list[tuple[ast.AST, ast.AST]]:
+        if isinstance(target, ast.Name):
+            return [(target, value)]
+        if isinstance(target, (ast.Tuple, ast.List)) and isinstance(value, (ast.Tuple, ast.List)):
+            return list(zip(target.elts, value.elts))
+        return []
+
+    @staticmethod
+    def _is_pure_compile_time_expr(node: ast.AST) -> bool:
+        if isinstance(node, ast.Constant):
+            return isinstance(node.value, (bool, int, float, str))
+        if isinstance(node, ast.UnaryOp) and isinstance(node.op, (ast.USub, ast.UAdd)):
+            return FlowAnalyzer._is_pure_compile_time_expr(node.operand)
+        if isinstance(node, ast.List) and node.elts:
+            return all(FlowAnalyzer._is_pure_compile_time_expr(item) for item in node.elts)
+        return False
+
+    @staticmethod
+    def _is_true(node: ast.AST) -> bool:
+        return isinstance(node, ast.Constant) and node.value is True
+
+    @staticmethod
+    def _literal_int(node: ast.AST) -> int | None:
+        if isinstance(node, ast.Constant) and isinstance(node.value, int) and not isinstance(node.value, bool):
+            return int(node.value)
+        if isinstance(node, ast.UnaryOp) and isinstance(node.op, ast.USub):
+            value = FlowAnalyzer._literal_int(node.operand)
+            return -value if value is not None else None
+        return None
+
+    @classmethod
+    def _for_iter_is_statically_nonempty(cls, node: ast.AST) -> bool:
+        if isinstance(node, ast.Call) and isinstance(node.func, ast.Name) and node.func.id == "range":
+            return cls._range_is_statically_nonempty(node)
+        # Fixed-list literals are non-empty by frontend rule. A named fixed list
+        # also has a compile-time positive length, even though the type is not
+        # available in this phase; V1 never permits an empty fixed list.
+        if isinstance(node, (ast.Name, ast.List)):
+            return True
+        if isinstance(node, ast.Call) and isinstance(node.func, ast.Name) and node.func.id == "enumerate":
+            return bool(node.args) and isinstance(node.args[0], (ast.Name, ast.List))
+        return False
+
+    @classmethod
+    def _range_is_statically_nonempty(cls, node: ast.AST) -> bool:
+        if not isinstance(node, ast.Call) or not isinstance(node.func, ast.Name) or node.func.id != "range":
+            return False
+        vals = [cls._literal_int(arg) for arg in node.args]
+        if any(v is None for v in vals):
+            return False
+        nums = [int(v) for v in vals if v is not None]
+        if len(nums) == 1:
+            start, stop, step = 0, nums[0], 1
+        elif len(nums) == 2:
+            start, stop, step = nums[0], nums[1], 1
+        elif len(nums) == 3:
+            start, stop, step = nums
+        else:
+            return False
+        if step == 0:
+            return False
+        return (step > 0 and start < stop) or (step < 0 and start > stop)
+
+
+def analyze_flow(resolved: ResolvedModule) -> FlowAnalyzedModule:
+    return FlowAnalyzer(resolved).analyze()