gh-11: Add type annotations, enforce static typing in ASM-Lang interpreter

Author: python-processing-unit

asm-lang.exe

@@ -7,12 +7,12 @@
 from typing import List, Optional
 import threading
 
-from extensions import ASMExtensionError, ReplContext, load_runtime_services
+from extensions import ASMExtensionError, ReplContext, load_runtime_services, RuntimeServices
 from interpreter import ASMRuntimeError, Environment, ExitSignal, Interpreter, TracebackFormatter
 from lexer import ASMParseError, Lexer
 from parser import Parser, Statement
 
-import tkinter  # Ensure tkinter is available for GUI extensions
+import tkinter # needed for the gui extension (ext\gui.py) to work for the frozen executable
 
 def _print_error(msg: str) -> None:
     """Print an error message to stderr prefixed with U+0007 (BEL)."""
@@ -61,7 +61,7 @@ def _parse_statements_from_source(text: str, filename: str, *, type_names: Optio
     return program.statements
 
 
-def run_repl(*, verbose: bool, services) -> int:
+def run_repl(*, verbose: bool, services: Optional[RuntimeServices]) -> int:
     print("\x1b[38;2;153;221;255mASM-Lang\033[0m REPL. Enter statements, blank line to run buffer.") # "ASM-Lang" in light blue
     # Use "<repl>" as the REPL's effective source filename so that MAIN() and imports behave
     had_output = False
@@ -101,6 +101,7 @@ def _output_sink(text: str) -> None:
     picked = services.hook_registry.pick_repl() if services is not None else None
     if picked is not None:
         _name, runner, _ext = picked
+        assert services is not None
         ctx = ReplContext(
             verbose=verbose,
             services=services,
@@ -210,6 +211,7 @@ def _output_sink(text: str) -> None:
             continue
 
         buffer.append(line)
+    return 0
 
 
 def run_cli(argv: Optional[List[str]] = None) -> int:
@@ -272,7 +274,7 @@ def run_cli(argv: Optional[List[str]] = None) -> int:
     except BaseException as exc:
         return _print_internal_error(exc=exc, interpreter=None, verbose=bool(getattr(args, "verbose", False)))
 
-    program: Optional[str] = None
+    program = None
     if remaining:
         if len(remaining) > 1:
             _print_error("Too many non-extension inputs; expected a single program argument")

asm-lang.py

@@ -126,7 +126,7 @@ def pick_repl(self) -> Optional[Tuple[str, Callable[["ReplContext"], int], str]]
         if len(self._repls) == 1:
             return self._repls[0]
         names = ", ".join(sorted({n for n, _, _ in self._repls}))
-        raise ASMExtensionError(f"Multiple REPL providers registered ({names}); select one explicitly is not implemented")
+        raise ASMExtensionError(f"Multiple REPL providers registered ({names}); explicit selection not implemented")
 
 
 @dataclass(frozen=True)
@@ -181,7 +181,7 @@ def register_operator(
                 qualified = f"{prefix}.{qualified}"
         self._services.operators.append((qualified, int(min_args), None if max_args is None else int(max_args), impl, doc))
 
-    def operator(self, name: str, min_args: int, max_args: Optional[int] = None, *, doc: str = ""):
+    def operator(self, name: str, min_args: int, max_args: Optional[int] = None, *, doc: str = "") -> Callable[[Callable[..., Any]], Callable[..., Any]]:
         def deco(fn: Callable[..., Any]) -> Callable[..., Any]:
             self.register_operator(name, min_args, max_args, fn, doc=doc)
             return fn
@@ -211,14 +211,14 @@ def register_type(
             )
         )
 
-    def type(self, name: str, *, printable: bool = True):
+    def type(self, name: str, *, printable: bool = True) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
         def deco(fn: Callable[..., Any]) -> Callable[..., Any]:
             raise ASMExtensionError("Use register_type(...) explicitly; decorator form not supported")
 
         return deco
 
     # ---- hooks ----
-    def on_event(self, event: str, handler: Optional[Callable[..., None]] = None, *, priority: int = 0):
+    def on_event(self, event: str, handler: Optional[Callable[..., None]] = None, *, priority: int = 0) -> Callable[..., None] | Callable[[Callable[..., None]], Callable[..., None]]:
         if handler is None:
             def deco(fn: Callable[..., None]) -> Callable[..., None]:
                 self._services.hook_registry.on_event(event, fn, priority=priority, ext_name=self._ext_name)
@@ -227,7 +227,7 @@ def deco(fn: Callable[..., None]) -> Callable[..., None]:
         self._services.hook_registry.on_event(event, handler, priority=priority, ext_name=self._ext_name)
         return handler
 
-    def every_n_steps(self, every_n: int, handler: Optional[Callable[[Any, StepContext], None]] = None, *, name: str = ""):
+    def every_n_steps(self, every_n: int, handler: Optional[Callable[[Any, StepContext], None]] = None, *, name: str = "") -> Callable[[Any, StepContext], None] | Callable[[Callable[[Any, StepContext], None]], Callable[[Any, StepContext], None]]:
         if handler is None:
             def deco(fn: Callable[[Any, StepContext], None]) -> Callable[[Any, StepContext], None]:
                 self._services.hook_registry.add_step_rule(name=name or fn.__name__, every_n=every_n, handler=fn, ext_name=self._ext_name)