Introduce the astcompile pass

CLAUDE.md

@@ -120,5 +120,22 @@ spy -O 1 -g your_file.spy         # With optimization and debug symbols
   one `Test*` class per `test_*.py` file.
 
 
+## When to write unit tests
+
+A unit test is worth writing only if the complexity of the thing being tested is
+high enough to justify it.
+
+A test that just mirrors a declaration or configuration is a **change-detector**,
+not a safety net. If updating the code always means updating the test in lockstep,
+the test adds no value — it only adds maintenance burden. Tests should verify
+*behavior that emerges from the interaction of multiple pieces*, not re-state what
+a single declaration says.
+
+If the logic is trivial AND it is exercised downstream by other tests (e.g.
+integration/compiler tests), it is fine to rely on those instead of writing
+dedicated unit tests. For example: if you put the wrong `@astnode("...")` spec on a
+node class, the compiler tests will catch it. A unit test that just asserts
+`SomeNode._valid_states == frozenset({"parsed"})` adds nothing.
+
 ## GH PR Guidelines
 - When creating a PR, describe what you did, but don't include the "test plan" section.

spy/analyze/importing.py

@@ -8,6 +8,7 @@
 
 from spy import ast
 from spy.analyze.scope import ScopeAnalyzer
+from spy.astcompile import astcompile
 from spy.errors import SPyError
 from spy.fqn import FQN
 from spy.parser import Parser
@@ -22,7 +23,7 @@
 MODULE = Union[ast.Module, "W_Module", None]
 
 # Cache version: increment this when ast.Module or SymTable structure changes
-SPYC_VERSION = 7
+SPYC_VERSION = 8
 
 
 @dataclass
@@ -219,7 +220,7 @@ def _save_spyc(self, mod: ast.Module, spyc: py.path.local) -> None:
             if not self.vm.robust_import_caching:
                 raise
 
-    def parse_all(self) -> None:
+    def astcompile_all(self) -> None:
         while self.queue:
             modname = self.queue.popleft()
 
@@ -239,7 +240,7 @@ def parse_all(self) -> None:
                 if modname not in self.deps:
                     self.deps[modname] = OrderedSet()
 
-                mod = self.parse_one(modname, spyfile)
+                mod = self.astcompile_one(modname, spyfile)
                 self.mods[modname] = mod
 
                 # record implicit imports
@@ -256,9 +257,9 @@ def parse_all(self) -> None:
                 # we couldn't find .spy for this modname
                 self.mods[modname] = None
 
-    def parse_one(self, modname: str, spyfile: py.path.local) -> ast.Module:
+    def astcompile_one(self, modname: str, spyfile: py.path.local) -> ast.Module:
         """
-        Parse a module AND run ScopeAnalyzer on it.
+        Parse a module, run ScopeAnalyzer, run astcompile.
         """
         # try to load from cache first
         mod = None
@@ -270,14 +271,18 @@ def parse_one(self, modname: str, spyfile: py.path.local) -> ast.Module:
                     return mod
 
         # no cache found, parse it
-        parser = Parser.from_filename(str(spyfile))
-        mod = parser.parse()
-        scopes = self.analyze_one(modname, mod)
-        mod.symtable = scopes.by_module()
+        parsed_mod = self.parse_one(spyfile)
+        scopes = self.analyze_one(modname, parsed_mod)
+        parsed_mod.symtable = scopes.by_module()
+        compiled_mod = astcompile(parsed_mod)
 
         if self.use_spyc:
-            self._save_spyc(mod, spyc)
-        return mod
+            self._save_spyc(compiled_mod, spyc)
+        return compiled_mod
+
+    def parse_one(self, spyfile: py.path.local) -> ast.Module:
+        parser = Parser.from_filename(str(spyfile))
+        return parser.parse()
 
     def analyze_one(self, modname: str, mod: ast.Module) -> ScopeAnalyzer:
         scopes = ScopeAnalyzer(modname, mod)
@@ -316,7 +321,7 @@ def visit(modname: str) -> None:
     def import_all(self) -> None:
         from spy.vm.module import W_Module
 
-        assert self.mods, "call .parse_all() first"
+        assert self.mods, "call .astcompile_all() first"
         import_list = self.get_import_list()
         for modname in import_list:
             mod = self.mods[modname]
@@ -435,7 +440,7 @@ def pp_tree(self) -> None:
             ├── b1
             └── b2
         """
-        assert self.mods, "call .parse_all() first"
+        assert self.mods, "call .astcompile_all() first"
 
         # Constants for tree formatting
         # fmt: off