two-phase slice 12: nested module AST

NestedModule builds NkUnit(name, decls, body, imports) with a local
import accumulator and sets astDecl so the enclosing DeclSeq records it.
Nodes are inert.

Deferred: CLASS items (absent from the compiler's own sources), Lower.

Gates: suite 178/178; fixpoint OK (stage2 == stage3, 3034200 bytes).

See docs/summary_two-phase-slice12.md.

compiler/src/M2.atg

@@ -373,26 +373,41 @@ PRODUCTIONS
      scope at END. *)
   NestedModule                          (. VAR m1, m2: SymTab.Name;
                                              expNames: ARRAY [0 .. 63] OF SymTab.Name;
-                                             expCount, k: CARDINAL; .)
+                                             expCount, k: CARDINAL;
+                                             astNode, nImp, nImpTail:
+                                               AST.Node; .)
     = "MODULE"
       GetIdent<m1>                      (. IF NOT SymTab.Enter(m1,
                                              SymTab.KindModule) THEN
                                              SemError(200) END;
                                            SymTab.PushScope;
-                                           expCount := 0; .)
+                                           expCount := 0;
+                                           astNode := AST.MakeNode(AST.NkUnit);
+                                           AST.SetChild(astNode, 0,
+                                             AST.MakeLeaf(AST.NkIdent, m1));
+                                           astStmt := AST.NoNode;
+                                           astDecl := AST.NoNode;
+                                           nImp := AST.NoNode;
+                                           nImpTail := AST.NoNode; .)
       [ Priority ]
       ";"
-      { Import }
+      { Import                        (. AstAppend(AST.NkDeclSeq,
+                                             nImp, nImpTail, astDecl); .) }
       [ "EXPORT" [ "QUALIFIED" ]
         GetIdent<expNames[expCount]>    (. INC(expCount); .)
         { "," GetIdent<expNames[expCount]>
                                         (. INC(expCount); .) }
         ";" ]
       DeclSeq
-      [ "BEGIN"                         (. QbeGen.BeginInit(m1); .)
+      [ "BEGIN"                         (. astStmt := AST.NoNode;
+                                           QbeGen.BeginInit(m1); .)
         [ StatSeq ]                     (. QbeGen.EndInit; .) ]
       "END"
-      GetIdent<m2>                      (. IF NOT SymTab.Equal(m1, m2) THEN
+      GetIdent<m2>                      (. AST.SetChild(astNode, 1, astDecl);
+                                           AST.SetChild(astNode, 2, astStmt);
+                                           AST.SetChild(astNode, 3, nImp);
+                                           astDecl := astNode;
+                                           IF NOT SymTab.Equal(m1, m2) THEN
                                              SemError(202) END;
                                            k := 0;
                                            WHILE k < expCount DO

docs/plan-two-phase.md

@@ -92,12 +92,12 @@ Suggested slices, each ending in `build.sh` + `run_tests.sh` +
    `NkConstDecl`/`NkTypeDecl`/`NkVarDecl`/`NkProcDecl` (types referenced
    by the node `ty` index); `astUnit` holds `NkUnit(name, decls, body)`
    for all three unit kinds; builtin statements build `NkCall`s.
-   Deferred: `CLASS`, nested modules in the unit AST; `Lower`.
-   Also `docs/summary_two-phase-slice8.md` (`CASE`/`WITH`),
-   `docs/summary_two-phase-slice9.md` (brace/set literals),
-   `docs/summary_two-phase-slice10.md` (`ResultComp` + unbounded
-   `NkBlock`/`NkDeclSeq`) and `docs/summary_two-phase-slice11.md`
-   (imports).
+   Deferred: `CLASS` items (no class declarations in the compiler's own
+   sources); `Lower`.  Also `docs/summary_two-phase-slice8.md`
+   (`CASE`/`WITH`), `docs/summary_two-phase-slice9.md` (brace/set
+   literals), `docs/summary_two-phase-slice10.md` (`ResultComp` +
+   unbounded `NkBlock`/`NkDeclSeq`), `docs/summary_two-phase-slice11.md`
+   (imports) and `docs/summary_two-phase-slice12.md` (nested modules).
 5. **Flip**: bodies lower from the AST; delete `FwdPatchAll` /
    `FixLoadClass` / `FixStoreClass`, the `Design` forward-variable
    placeholder, and `pendVar*` if superseded.

docs/summary_two-phase-slice12.md

@@ -0,0 +1,40 @@
+# Two-phase refactor — slice 12 (nested modules)
+
+Branch `ast-stage-c`.  Suite **178/178**; self-hosting fixpoint **OK**
+(**3,034,200 bytes**; slice 11 was 3,032,308).
+
+## What landed
+
+`NestedModule` now builds an `NkUnit(name, decls, body, imports)` using
+its own local import accumulator (`nImp`/`nImpTail`), and sets `astDecl`
+to that node — so the enclosing `DeclSeq` records the nested module as a
+declaration.  A local accumulator keeps the enclosing unit's imports
+(`astImp`) intact.
+
+## Verified (temporary `AST.Dump`, then removed)
+
+```modula2
+MODULE nestdump;
+VAR x : INTEGER;
+MODULE Inner;
+  VAR y : INTEGER;
+BEGIN y := 5 END Inner;
+BEGIN x := 1 END nestdump.
+```
+
+gave the outer `NkUnit(nestdump, decls=[NkVarDecl x, NkUnit(Inner,
+decls=[NkVarDecl y], body=[y:=5])], body=[x:=1])`.
+
+## Still not covered
+
+- **`CLASS` / `CLASS IMPLEMENTATION`** items.  Note: the compiler's own
+  sources contain **no** actual class declarations (only the word in
+  comments and the scanner's keyword table), so this is not needed for
+  self-hosting validation — it is a user-facing OOP feature and a
+  sizeable slice of its own.
+- `Lower` + `.ssa` byte-compare.
+- `MaxChild` cap on `CASE` arms / `WITH` designators / call actuals.
+
+## Next
+
+`CLASS` (if desired) or the `Lower` walk.