fix grammar again

.claude/settings.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(python)",
+      "Bash(rm -rf __pycache__ */__pycache__)",
+      "Bash(python _smoke_test.py)"
+    ]
+  }
+}

Backend/_smoke_test.py

@@ -1,4 +1,3 @@
-"""Smoke test runner for restructure. Run after each phase: python _smoke_test.py"""
 import sys, os
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 
@@ -39,7 +38,6 @@ PROGRAMS = [
      ['age=20']),
     ('nestedreturn', 'root() { branch stop = frost; spring (stop) { reclaim; } plant("continued"); reclaim; }',
      ['continued']),
-    # ── increment/decrement on indexed/member operands (added by Part A) ──
     ('arr_postfix', 'root() { seed arr[3]; arr[0] = 1; arr[0]++; plant("v={}", arr[0]); reclaim; }',
      ['v=2']),
     ('arr_prefix',  'root() { seed arr[3]; arr[0] = 5; ++arr[0]; plant("v={}", arr[0]); reclaim; }',
@@ -54,7 +52,6 @@ PROGRAMS = [
      ['v=9']),
     ('arr_in_loop', 'root() { seed arr[3]; arr[0]=0; arr[1]=0; arr[2]=0; cultivate(seed i = 0; i < 3; i++) { arr[i]++; } plant("a={} b={} c={}", arr[0], arr[1], arr[2]); reclaim; }',
      ['a=1 b=1 c=1']),
-    # ── exponent-assign (added separately) ──
     ('exp_assign_seed', 'root() { seed x = 2; x **= 3; plant("{}", x); reclaim; }',
      ['8']),
     ('exp_assign_chain', 'root() { seed x = 2; x **= 3; x **= 2; plant("{}", x); reclaim; }',

Backend/ai/__init__.py

@@ -1,13 +1,2 @@
-# ============================================================================
-# AI PACKAGE - Chat-helper layer (Gemini integration + regex fallback)
-# ============================================================================
-# Contents:
-#   fallback.py - rule-based regex/keyword responder used when Gemini is
-#                 unavailable or rate-limited.
-#   prompt.txt  - system prompt that teaches the LLM how to talk about GAL.
-#
-# This package is NOT part of the compiler pipeline; server.py consumes it
-# only for the in-IDE "Ask" chat helper.
-# ============================================================================
 
 from .fallback import fallback_reply  # noqa: F401

Backend/ai/fallback.py

@@ -1,28 +1,10 @@
-"""
-NLP-based fallback responder for the GAL AI chat.
-
-Three-layer hybrid architecture:
-  Layer 1 — Rule Engine: regex matches compiler error messages → structured explanations
-  Layer 2 — Retriever: sentence-transformers (gal-mpnet-finetuned) semantic search over 50+ KB topics
-  Layer 3 — Default: help menu when nothing matches
-
-Plus: synonym expansion, greeting detection, follow-up context, multi-topic blending.
-Uses the #1 ranked sentence embedding model for best semantic matching accuracy.
-All heavy imports are deferred so the server binds its port immediately.
-"""
 
 import re as _re
 
-# Minimum cosine similarity score to return a topic match (else use default)
 _THRESHOLD = 0.35
 
 
-# ═══════════════════════════════════════════════════════════════════════
-# STRUCTURED RESPONSE BUILDER
-# ═══════════════════════════════════════════════════════════════════════
-
 def _structured_error(stage, cause, rule="", fix="", explanation=""):
-    """Build a structured error explanation from labeled slots."""
     parts = [f"**Stage:** {stage}", f"**Cause:** {cause}"]
     if rule:
         parts.append(f"**Rule:** {rule}")
@@ -46,14 +28,7 @@ def _runtime_err(cause, rule, fix, explanation=""):
     return _structured_error("Runtime (Interpreter)", cause, rule, fix, explanation)
 
 
-# ═══════════════════════════════════════════════════════════════════════
-# LAYER 1: RULE ENGINE — regex-based compiler error pattern matching
-# ═══════════════════════════════════════════════════════════════════════
-# Each entry: (compiled_regex, response_string_or_callable)
-# If callable, it receives the re.Match object and returns a string.
-
 _ERROR_PATTERNS = [
-    # ── Lexer Errors ──────────────────────────────────────────────
 
     (_re.compile(r"Identifier exceeds maximum length of 15 characters", _re.I),
      _lexer_err(
@@ -125,7 +100,6 @@ _ERROR_PATTERNS = [
          "/* This is a comment */  // Correct\n/* Unclosed comment      // ERROR",
      )),
 
-    # ── Parser: Operator Errors ───────────────────────────────────
 
     (_re.compile(r"'===' is not valid", _re.I),
      _parser_err(
@@ -149,7 +123,6 @@ _ERROR_PATTERNS = [
          "// BAD:  spring (a | b) { ... }\n// GOOD: spring (a || b) { ... }",
      )),
 
-    # ── Parser: Keyword Mistakes (generic — catches all 20+) ─────
 
     (_re.compile(r"'(\w+)' is not a GAL keyword\.\s*Use '(\w+)' instead", _re.I),
      lambda m: _parser_err(
@@ -159,7 +132,6 @@ _ERROR_PATTERNS = [
          "GAL uses botanical-themed keywords. See the keyword reference for all mappings.",
      )),
 
-    # ── Parser: Missing Delimiters ────────────────────────────────
 
     (_re.compile(r"Expected\s*['\"]?;['\"]?|Unexpected token.*Expected\s*['\"]?;['\"]?", _re.I),
      _parser_err(
@@ -249,7 +221,6 @@ _ERROR_PATTERNS = [
          "// BAD:  leaf c = '';\n// GOOD: leaf c = 'A';",
      )),
 
-    # ── Semantic Errors ───────────────────────────────────────────
 
     (_re.compile(r"Variable '(\w+)' already declared", _re.I),
      lambda m: _semantic_err(
@@ -414,7 +385,6 @@ _ERROR_PATTERNS = [
          "seed arr[] = {10, 20, 30};\nseed i = 1;\nplant(arr[i]);  // OK: seed index",
      )),
 
-    # ── Runtime Errors ────────────────────────────────────────────
 
     (_re.compile(r"Division by zero", _re.I),
      _runtime_err(
@@ -463,8 +433,6 @@ _ERROR_PATTERNS = [
 
 
 def _rule_engine_match(msg):
-    """Try each regex pattern against the user message.
-    Return a structured response string if matched, else None."""
     for pattern, response in _ERROR_PATTERNS:
         m = pattern.search(msg)
         if m:
@@ -472,13 +440,7 @@ def _rule_engine_match(msg):
     return None
 
 
-# ═══════════════════════════════════════════════════════════════════════
-# LAYER 2: EXPANDED KNOWLEDGE BASE (50+ topics)
-# ═══════════════════════════════════════���═══════════════════════════════
-# Each entry: (training_phrases_list, response_string)
-
 _KNOWLEDGE_BASE = [
-    # ── 1. Data types ─────────────────────────────────────────────
     ([
         "what are the data types",
         "data types in GAL",
@@ -526,7 +488,6 @@ leaf ch = 'A';
 branch flag = sunshine;
 ```"""),
 
-    # ── 2. Variables / declarations ───────────────────────────────
     ([
         "how to declare a variable",
         "variable declaration",
@@ -558,7 +519,6 @@ Constants use `fertile`:
 fertile seed MAX = 100;
 ```"""),
 
-    # ── 3. Arrays ─────────────────────────────────────────────────
     ([
         "how to use arrays",
         "array declaration",
@@ -593,7 +553,6 @@ seed grid[][] = {{1, 2}, {3, 4}};  // nested init
 ```
 Arrays are 0-indexed."""),
 
-    # ── 4. For loop (cultivate) ───────────────────────────────────
     ([
         "for loop",
         "cultivate loop",
@@ -631,7 +590,6 @@ cultivate(seed i = 0; i < TS(arr); i++) {
 }
 ```"""),
 
-    # ── 5. While loop (grow) ──────────────────────────────────────
     ([
         "while loop",
         "grow loop",
@@ -664,7 +622,6 @@ grow (count < 3) {
 - Use `prune;` (break) to exit early
 - Use `skip;` (continue) to skip to next iteration"""),
 
-    # ── 6. Do-while loop (tend...grow) ────────────────────────────
     ([
         "do while loop",
         "do-while loop",
@@ -698,7 +655,6 @@ tend {
 - Use `prune;` (break) to exit early
 - Use `skip;` (continue) to skip to next iteration"""),
 
-    # ── 7. Loops overview ─────────────────────────────────────────
     ([
         "how to make a loop",
         "loop types in GAL",
@@ -739,7 +695,6 @@ tend {
 
 Use `prune;` (break) and `skip;` (continue) inside loops."""),
 
-    # ── 8. If / else ──────────────────────────────────────────────
     ([
         "if else condition",
         "conditional statement",
@@ -778,7 +733,6 @@ spring (x > 0) {
 - `bud` = else if
 - `wither` = else"""),
 
-    # ── 9. Switch ─────────────────────────────────────────────────
     ([
         "switch case statement",
         "harvest variety soil",
@@ -811,7 +765,6 @@ harvest (choice) {
 - `soil` = default
 - `prune` = break"""),
 
-    # ── 10. Functions ─────────────────────────────────────────────
     ([
         "how to create a function",
         "function declaration definition",
@@ -856,7 +809,6 @@ root() {
 }
 ```"""),
 
-    # ── 11. Input (water) ─────────────────────────────────────────
     ([
         "how to read input",
         "get user input",
@@ -885,7 +837,6 @@ water(arr[i][j]);           // read into 2D array element
 ```
 `water(seed x)` is WRONG — don't combine type + variable name."""),
 
-    # ── 12. Output (plant) ────────────────────────────────────────
     ([
         "how to print output",
         "display show output",
@@ -917,7 +868,6 @@ Backtick concatenation may join `vine` and `leaf` values in plant():
 - `plant("Hello {}", name);` is valid formatting
 - `plant("Hello " ` name);` is valid string concatenation"""),
 
-    # ── 13. Bundles (structs) ─────────────────────────────────────
     ([
         "struct bundle record",
         "create a struct",
@@ -963,7 +913,6 @@ p.addr.zip = 1000;
 
 No inline init: `bundle Point p = {5, 10};` is NOT supported."""),
 
-    # ── 14. Operators ─────────────────────────────────────────────
     ([
         "operators in GAL",
         "arithmetic comparison logical",
@@ -986,7 +935,6 @@ No inline init: `bundle Point p = {5, 10};` is NOT supported."""),
 
 `**` (exponent) is NOT supported."""),
 
-    # ── 15. Errors / debugging ────────────────────────────────────
     ([
         "error bug debug fix",
         "why is my code not working",
@@ -1017,7 +965,6 @@ No inline init: `bundle Point p = {5, 10};` is NOT supported."""),
 
 Tip: Check the OUTPUT panel for line numbers to locate errors."""),
 
-    # ── 16. Keywords reference ────────────────────────────────────
     ([
         "keyword reference list",
         "all GAL keywords",
@@ -1054,7 +1001,6 @@ Tip: Check the OUTPUT panel for line numbers to locate errors."""),
 | `frost` | false |
 | `~` | unary minus |"""),
 
-    # ── 17. Example / template ────────────────────────────────────
     ([
         "example program template",
         "hello world starter code",
@@ -1083,7 +1029,6 @@ root() {
 ```
 Every GAL program needs a `root()` function as the entry point."""),
 
-    # ── 18. Convert from C ────────────────────────────────────────
     ([
         "convert C to GAL",
         "translate from C language",
@@ -1105,7 +1050,6 @@ Every GAL program needs a `root()` function as the entry point."""),
 - `return` -> `reclaim`, `void` -> `empty`
 - `-x` -> `~x` (unary negation uses tilde)"""),
 
-    # ── 19. Comments ──────────────────────────────────────────────
     ([
         "how to write comments in GAL code",
         "comment syntax slash slash",
@@ -1125,7 +1069,6 @@ Every GAL program needs a `root()` function as the entry point."""),
 ```
 Same syntax as C/Java."""),
 
-    # ── 20. Identifier rules ──────────────────────────────────────
     ([
         "identifier rules naming",
         "variable name rules",
@@ -1144,7 +1087,6 @@ Same syntax as C/Java."""),
 Valid: `x`, `count`, `myVar`, `total_sum`, `playerScore1`
 Invalid: `2count`, `_name`, `thisIsWayTooLong`"""),
 
-    # ── 21. Type casting ──────────────────────────────────────────
     ([
         "type casting conversion",
         "convert between types",
@@ -1171,7 +1113,6 @@ Supported casts:
 - `(vine)` — converts anything to string
 - `(branch)` — converts to boolean"""),
 
-    # ── 22. Array built-in operations ─────────────────────────────
     ([
         "array built-in methods operations",
         "append to array add element",
@@ -1210,7 +1151,6 @@ seed slen = TS("hello"); // 5
 leaf chars[] = taper("abc"); // chars = ['a','b','c']
 ```"""),
 
-    # ── 23. Escape sequences ──────────────────────────────────────
     ([
         "escape sequences special characters",
         "newline tab in string",
@@ -1239,7 +1179,6 @@ plant("Name:\\tAlice");
 plant("She said \\"hi\\"");
 ```"""),
 
-    # ── 24. String concatenation ──────────────────────────────────
     ([
         "string concatenation combine join",
         "concatenate two strings",
@@ -1262,11 +1201,7 @@ For output, prefer format strings:
 plant("{} {}", first, second);  // cleaner
 ```"""),
 
-    # ══════════════════════════════════════════════════════════════
-    #  NEW TOPICS (25–54) — expanded coverage
-    # ══════════════════════════════════════════════════════════════
 
-    # ── 25. Program structure & root() ────────────────────────────
     ([
         "program structure organization",
         "where does root go",
@@ -1302,7 +1237,6 @@ root() {
 - `root()` must end with `reclaim;`
 - No code is allowed after `root()`'s closing `}`"""),
 
-    # ── 26. Scope rules ───────────────────────────────────────────
     ([
         "scope rules variable visibility",
         "local variable global variable",
@@ -1346,7 +1280,6 @@ pollinate empty test() {
 
 Variables in inner scopes can see outer scopes, but not vice versa."""),
 
-    # ── 27. Constants (fertile) ───────────────────────────────────
     ([
         "how to make constant",
         "fertile keyword constant",
@@ -1372,7 +1305,6 @@ fertile branch DEBUG = frost;
 - Multiple `fertile` declarations on one line are **not** allowed
 - `fertile` goes before the type: `fertile seed`, not `seed fertile`"""),
 
-    # ── 28. Boolean values ────────────────────────────────────────
     ([
         "boolean values in GAL",
         "sunshine and frost meaning",
@@ -1403,7 +1335,6 @@ branch equal = (x == y);    // depends on x, y
 
 Use `!` to negate: `!sunshine` = `frost`"""),
 
-    # ── 29. Function return types ─────────────────────────────────
     ([
         "function return type options",
         "empty function void return",
@@ -1442,7 +1373,6 @@ pollinate empty sayHi() {          // returns nothing
 - Non-empty functions must provide a value in their required final `reclaim`
 - The CFG requires every function to end with `reclaim`"""),
 
-    # ── 30. Recursive functions ───────────────────────────────────
     ([
         "recursive function in GAL",
         "recursion example",
@@ -1471,7 +1401,6 @@ root() {
 - Each recursive call should move toward the base case
 - Be mindful of the 10,000 iteration limit (applies to deep recursion too)"""),
 
-    # ── 31. Nested conditionals ───────────────────────────────────
     ([
         "nested if statements",
         "if inside if nested",
@@ -1510,7 +1439,6 @@ bud (condition3) { ... }
 wither { ... }
 ```"""),
 
-    # ── 32. Prune (break) & skip (continue) ──────────────────────
     ([
         "break statement prune",
         "continue statement skip",
@@ -1544,7 +1472,6 @@ cultivate (seed i = 0; i < 10; i++) {
 - `skip` can only be used in loops (not in `harvest`)
 - Using them outside their valid context gives a semantic error"""),
 
-    # ── 33. Nested loops ──────────────────────────────────────────
     ([
         "nested loop inside loop",
         "double loop two loops",
@@ -1574,7 +1501,6 @@ cultivate (seed r = 0; r < 3; r++) {
 
 Note: `prune` only exits the **innermost** loop. To exit an outer loop, use a flag variable."""),
 
-    # ── 34. 2D arrays detailed ────────────────────────────────────
     ([
         "two dimensional array detailed",
         "matrix operations rows columns",
@@ -1616,7 +1542,6 @@ cultivate (seed i = 0; i < 3; i++) {
 
 Arrays are 0-indexed: valid indices for `arr[M][N]` are `[0..M-1][0..N-1]`."""),
 
-    # ── 35. Array of bundles ──────────────────────────────────────
     ([
         "array of bundles structs",
         "list of struct objects",
@@ -1654,7 +1579,6 @@ root() {
 **Syntax:** `bundle <Type> <name>[<size>];`
 Then access: `name[index].member`"""),
 
-    # ── 36. Nested bundles ────────────────────────────────────────
     ([
         "nested bundle struct inside struct",
         "bundle with bundle member",
@@ -1690,7 +1614,6 @@ root() {
 
 Define inner bundles **before** the outer bundle that uses them."""),
 
-    # ── 37. TS() function ─────────────────────────────────────────
     ([
         "ts function get length",
         "array length size",
@@ -1719,7 +1642,6 @@ cultivate (seed i = 0; i < TS(arr); i++) {
 - Does NOT work on `seed`, `tree`, `leaf`, or `branch` scalars
 - `TS()` is GAL's equivalent of `len()` / `.length`"""),
 
-    # ── 38. Taper() function ──────────────────────────────────────
     ([
         "taper function usage",
         "split string into characters",
@@ -1746,7 +1668,6 @@ cultivate (seed i = 0; i < TS(chars); i++) {
 - Works on `vine` (string) values
 - `taper()` is GAL's equivalent of `split('')` / `toCharArray()`"""),
 
-    # ── 39. Operator precedence ───────────────────────────────────
     ([
         "operator precedence order",
         "which operator evaluated first",
@@ -1772,7 +1693,6 @@ seed result = (2 + 3) * 4;  // 20, not 14
 branch check = (a > 0) && (b < 10);
 ```"""),
 
-    # ── 40. Increment / decrement ─────────────────────────────────
     ([
         "prefix postfix increment",
         "i++ vs ++i difference",
@@ -1807,7 +1727,6 @@ count--;   // count = 1
 - Cannot be chained: `x++++` is invalid
 - Cannot combine with binary ops: `x++ + 1` needs separate statements"""),
 
-    # ── 41. Unary negation (tilde) ────────────────────────────────
     ([
         "tilde operator negation",
         "negative number in GAL",
@@ -1837,7 +1756,6 @@ seed neg = ~42;      // -42
 tree negPi = ~3.14;  // -3.14
 ```"""),
 
-    # ── 42. Compound assignment ─────────────��─────────────────────
     ([
         "compound assignment operators",
         "plus equals minus equals",
@@ -1869,7 +1787,6 @@ score %= 5;     // score = 2
 - `%=` requires `seed` operands (modulo needs integers)
 - Cannot use on `fertile` (const) variables"""),
 
-    # ── 43. Format strings in plant() ─────────────────────────────
     ([
         "format string in plant",
         "placeholder curly braces",
@@ -1900,7 +1817,6 @@ plant("Name: {}, Age: {}", name, 25);   // mixed types
 // GOOD: plant("{} {}", a, b);        // 2 placeholders, 2 args
 ```"""),
 
-    # ── 44. Limits & constraints ──────────────────────────────────
     ([
         "limits constraints maximum GAL",
         "what are the GAL limits",
@@ -1933,7 +1849,6 @@ plant("Name: {}, Age: {}", name, 25);   // mixed types
 - Arrays are 0-indexed
 - `root()` function is required"""),
 
-    # ── 45. Compiler stages ───────────────────────────────────────
     ([
         "how does compiler work",
         "compilation process stages",
@@ -1969,7 +1884,6 @@ Source Code → Lexer → Parser → Semantic Analyzer → Interpreter
 **5. ICG** (`icg.py`) — Generates three-address code (parallel to semantic):
 - Produces intermediate representation for analysis"""),
 
-    # ── 46. Error: missing semicolons ─────────────────────────────
     ([
         "forgot semicolon error",
         "where do I put semicolons",
@@ -1998,7 +1912,6 @@ Source Code → Lexer → Parser → Semantic Analyzer → Interpreter
 - Functions: `pollinate seed fn() { ... }`
 - `root()`: `root() { ... }`"""),
 
-    # ── 47. Error: type mismatches ────────────────────────────────
     ([
         "type mismatch error help",
         "cannot assign wrong type",
@@ -2033,7 +1946,6 @@ branch b = 5;        // ERROR: seed → branch
 - `!` only works on `branch`
 - Comparisons require compatible types"""),
 
-    # ── 48. Error: undeclared variables ────────────────────────────
     ([
         "variable not declared error",
         "undefined undeclared variable",
@@ -2069,7 +1981,6 @@ seed x = 10;
 // Fix: move declaration before use
 ```"""),
 
-    # ── 49. Error: wrong C keywords ───────────────────────────────
     ([
         "used wrong keyword from C",
         "if instead of spring",
@@ -2102,7 +2013,6 @@ GAL uses botanical-themed keywords. If you use C/Java/Python keywords, the compi
 
 Tip: Use the keyword reference for the complete mapping."""),
 
-    # ── 50. Error: fertile (const) issues ─────────────────────────
     ([
         "fertile constant error",
         "cannot reassign fertile",
@@ -2142,7 +2052,6 @@ fertile seed B = 2;
 - Only literal values (no expressions): `fertile seed X = 2 + 3;` is invalid
 - `fertile` goes before the type: `fertile seed`, not `seed fertile`"""),
 
-    # ── 51. Example: Factorial / recursion ─────────────────────────
     ([
         "factorial example program",
         "recursive example code",
@@ -2184,7 +2093,6 @@ root() {
 }
 ```"""),
 
-    # ── 52. Example: Array operations ─────────────────────────────
     ([
         "array operations example",
         "sum of array elements",
@@ -2241,7 +2149,6 @@ root() {
 }
 ```"""),
 
-    # ── 53. Example: Bubble sort ──────────────────────────────────
     ([
         "sorting example program",
         "bubble sort GAL code",
@@ -2274,7 +2181,6 @@ root() {
 }
 ```"""),
 
-    # ── 54. Example: Bundle usage ─────────────────────────────────
     ([
         "bundle struct example program",
         "complete bundle example",
@@ -2315,7 +2221,6 @@ root() {
 }
 ```"""),
 
-    # ── Topic 55: GAL vs C comparison overview ──────────────────────
     ([
         "difference between GAL and C", "GAL vs C", "how is GAL different from C",
         "compare GAL and C", "GAL compared to C", "what makes GAL unique",
@@ -2354,7 +2259,6 @@ root() {
 - GAL uses `~` for **unary negation** (not `-`)
 - Format strings use `{}` placeholders (like Python), not `%d`/`%s`"""),
 
-    # ── Topic 56: Common mistakes / pitfalls ────────────────────────
     ([
         "common mistakes in GAL", "GAL pitfalls", "beginners mistakes",
         "what mistakes do people make", "things to watch out for in GAL",
@@ -2394,7 +2298,6 @@ root() {
 
 10. **Array index out of bounds** — indices are 0 to `TS(arr)-1`"""),
 
-    # ── Topic 57: How to debug GAL code ─────────────────────────────
     ([
         "how to debug GAL", "debugging GAL code", "my GAL code doesn't work",
         "GAL code not working", "how to fix GAL errors", "debug my code",
@@ -2428,7 +2331,6 @@ The compiler tells you exactly what's wrong and which line. Error messages inclu
 
 **Pro tip:** Paste any error message into this chat — I can explain it in detail!"""),
 
-    # ── Topic 58: What is GAL? ──────────────────────────────────────
     ([
         "what is GAL", "what is the GAL language", "tell me about GAL",
         "GAL programming language", "what is this language", "about GAL",
@@ -2454,7 +2356,6 @@ root() {
 ```
 This prints "Hello, Garden!" — `root()` is like `main()`, `plant()` is like `printf()`, and `reclaim` is like `return`."""),
 
-    # ── Topic 59: How to run a GAL program ──────────────────────────
     ([
         "how to run GAL", "how to execute", "run my program", "how to compile",
         "how to use this IDE", "how to use the editor", "where do I type code",
@@ -2486,7 +2387,6 @@ root() {
 
 Just type this in the editor and hit Run!"""),
 
-    # ── Topic 60: String operations in GAL ──────────────────────────
     ([
         "string operations", "how to work with strings", "vine operations",
         "string manipulation", "string functions", "what can I do with strings",
@@ -2529,7 +2429,6 @@ plant("Name: {}, Length: {}", name, TS(name));
 - `\\\\"` — literal double quote
 - `\\\\` — literal backslash"""),
 
-    # ── Topic 61: Number operations / math in GAL ───────────────────
     ([
         "math in GAL", "arithmetic operations", "math operations",
         "how to do math", "calculations in GAL", "number operations",
@@ -2573,19 +2472,14 @@ x %= 4;   // x = 2
 ]
 
 
-# ═══════════════════════════════════════════════════════════════════════
-# Sentence-Transformers (gal-mpnet-finetuned) — lazy-loaded on first query
-# ═══════════════════════════════════════════════════════════════════════
-
 _st_model = None
 _phrase_embeddings = None
 _phrase_topic_idx = []
 _responses = []
-_last_topic_idx = None          # track last matched topic for follow-ups
-_last_query = ""                # last user message for dedup
+_last_topic_idx = None
+_last_query = ""
 
 
-# ── GAL synonym map: C/common terms → GAL equivalents ────────────────
 _SYNONYMS = {
     "int":       "seed",    "integer":    "seed",
     "float":     "tree",    "double":     "tree",   "decimal": "tree",
@@ -2633,9 +2527,6 @@ _SYNONYMS = {
     "number":    "seed tree integer float arithmetic",
 }
 
-# ── Reverse map: GAL keywords → concept descriptions ─────────────────
-# When a user casually says "cultivate" or "tree", we expand it into
-# a rich query the embedding model can match against KB topics.
 _GAL_KEYWORD_MAP = {
     "seed":       "seed data type integer variable declaration",
     "tree":       "tree data type float decimal variable declaration",
@@ -2671,8 +2562,6 @@ _GAL_KEYWORD_MAP = {
 }
 
 
-# ── Greeting / meta patterns ─────────────────────────────────────────
-
 _GREETING_PATTERNS = [
     (_re.compile(r"^\s*(hi|hello|hey|howdy|sup|yo|greetings|good\s*(morning|afternoon|evening))\b", _re.I),
      "Hey there! I'm the GAL AI Assistant. Ask me anything about GAL — data types, loops, functions, arrays, I/O, and more!"),
@@ -2681,19 +2570,17 @@ _GREETING_PATTERNS = [
     (_re.compile(r"^\s*(bye|goodbye|see\s*ya|later|cya)\b", _re.I),
      "Goodbye! Happy coding with GAL! 🌱"),
     (_re.compile(r"\b(what can you do|help me|what do you know|how can you help)\b", _re.I),
-     None),  # None → return _DEFAULT_RESPONSE (the help menu)
+     None),
     (_re.compile(r"^\s*(who are you|what are you)\b", _re.I),
      "I'm the GAL AI Assistant — I help with GAL syntax, concepts, and debugging. Ask me about data types, loops, functions, arrays, or anything else in GAL!"),
 ]
 
 
 def _encode(texts):
-    """Encode texts using sentence-transformers (returns L2-normalised embeddings)."""
     return _st_model.encode(texts, normalize_embeddings=True, show_progress_bar=False)
 
 
 def _ensure_model():
-    """Load sentence-transformers model and encode training phrases on first call."""
     global _st_model, _phrase_embeddings, _phrase_topic_idx, _responses
     if _st_model is not None:
         return
@@ -2701,7 +2588,6 @@ def _ensure_model():
     from sentence_transformers import SentenceTransformer
     import os
 
-    # Prefer fine-tuned model, fall back to base
     finetuned = os.path.join(os.path.dirname(__file__), "..", "gal-mpnet-finetuned")
     if os.path.isdir(finetuned):
         _st_model = SentenceTransformer(finetuned)
@@ -2721,7 +2607,6 @@ def _ensure_model():
     _phrase_embeddings = _encode(all_phrases)
 
 
-# Default fallback when no topic is similar enough
 _DEFAULT_RESPONSE = """I can help with GAL syntax and concepts! Try asking about:
 - **Data types**: seed, tree, leaf, vine, branch
 - **Variables**: declarations, constants (`fertile`), scope rules
@@ -2740,8 +2625,6 @@ Or ask for "keyword reference", "example program", or "how does the compiler wor
 
 *Note: I'm running in offline mode right now. For more detailed help, try again later when the AI service is available.*"""
 
-# ── Conversational wrappers ─────────────────────────────────────────
-# These make retrieval answers feel more natural (like Gemini would respond)
 import random as _random
 
 _CONFIDENT_INTROS = [
@@ -2751,7 +2634,7 @@ _CONFIDENT_INTROS = [
     "Absolutely! ",
     "Good question — ",
     "Here you go:\n\n",
-    "",  # sometimes no intro feels most natural
+    "",
     "",
 ]
 
@@ -2780,40 +2663,31 @@ _OUTROS = [
     "\n\n---\n*Feel free to ask follow-up questions!*",
     "\n\n---\n*Let me know if you need more details on any part!*",
     "\n\n---\n*Want me to explain any part further?*",
-    "",  # sometimes no outro
+    "",
     "",
 ]
 
-# ── Conversation memory (per-process, lightweight) ──────────────────
-_conv_history = []       # list of (query, topic_idx, score) tuples
-_MAX_HISTORY = 8         # remember last 8 exchanges
+_conv_history = []
+_MAX_HISTORY = 8
 
 
 def _expand_query(text):
-    """Inject GAL synonyms into the query so the model sees both vocabularies.
-    Also resolves bare GAL keywords (e.g. 'cultivate') into rich concept
-    descriptions so short/casual queries match KB topics."""
     words = text.lower().split()
     extras = set()
 
-    # Forward: C/common terms → GAL equivalents
     for w in words:
         if w in _SYNONYMS:
             extras.add(_SYNONYMS[w])
 
-    # Also check 2-word combos (e.g. "else if" → "bud")
     lower = text.lower()
     for phrase, replacement in _SYNONYMS.items():
         if " " in phrase and phrase in lower:
             extras.add(replacement)
 
-    # Reverse: GAL keywords → concept descriptions
-    # This is the key for casual queries like "what is cultivate"
     for w in words:
         if w in _GAL_KEYWORD_MAP:
             extras.add(_GAL_KEYWORD_MAP[w])
 
-    # Also check multi-word GAL constructs in the raw text
     for kw, desc in _GAL_KEYWORD_MAP.items():
         if " " in kw and kw in lower:
             extras.add(desc)
@@ -2824,7 +2698,6 @@ def _expand_query(text):
 
 
 def _detect_intent(msg):
-    """Classify user intent to pick better response framing."""
     low = msg.lower()
     if any(w in low for w in ["how do i", "how to", "how can i", "how would"]):
         return "how-to"
@@ -2844,22 +2717,18 @@ def _detect_intent(msg):
 
 
 def _is_followup(msg):
-    """Detect if the user is asking a follow-up to the previous topic."""
     low = msg.lower().split()
-    # Short pronoun-based queries
     if len(low) <= 5 and any(w in msg.lower() for w in [
         "it", "that", "this", "those", "them", "more", "also",
         "too", "same", "again", "another", "other"
     ]):
         return True
-    # "tell me more" / "explain further" type
     if _detect_intent(msg) == "more":
         return True
     return False
 
 
 def _pick_intro(score, intent, is_followup):
-    """Choose a conversational intro based on confidence and context."""
     if is_followup:
         return _random.choice(_FOLLOWUP_INTROS)
     if score > 0.6:
@@ -2870,21 +2739,17 @@ def _pick_intro(score, intent, is_followup):
 
 
 def _wrap_response(raw_response, score, intent, is_followup, has_blend=False):
-    """Wrap a raw KB response with conversational framing."""
     intro = _pick_intro(score, intent, is_followup)
     outro = _random.choice(_OUTROS) if not has_blend else ""
     return intro + raw_response + outro
 
 
 def fallback_reply(user_message):
-    """Hybrid fallback: greeting → rule engine → semantic retriever → default.
-    Enhanced with conversational wrapping, intent detection, and conversation memory."""
     import numpy as np
     global _last_topic_idx, _last_query
 
     msg = user_message.strip()
 
-    # ── Layer 0: Greeting / meta patterns ─────────────────────────
     for pattern, response in _GREETING_PATTERNS:
         if pattern.search(msg):
             return response if response else _DEFAULT_RESPONSE
@@ -2892,11 +2757,9 @@ def fallback_reply(user_message):
     if not msg or len(msg) < 2:
         return _DEFAULT_RESPONSE
 
-    # Allow short queries if they contain a known GAL keyword
     if len(msg) < 4 and msg.lower() not in _GAL_KEYWORD_MAP:
         return _DEFAULT_RESPONSE
 
-    # ── Layer 1: Rule Engine — exact compiler error matching ──────
     rule_match = _rule_engine_match(msg)
     if rule_match:
         _last_query = msg
@@ -2905,26 +2768,20 @@ def fallback_reply(user_message):
             _conv_history.pop(0)
         return rule_match
 
-    # ── Layer 2: Semantic Retriever — similarity search ───────────
     _ensure_model()
 
     intent = _detect_intent(msg)
     is_followup = _is_followup(msg) and _conv_history
 
-    # Synonym expansion
     expanded = _expand_query(msg)
 
-    # Follow-up context injection — use conversation history
     if is_followup and _conv_history:
-        # Grab last 1-2 queries for context
         recent = [h[0] for h in _conv_history[-2:]]
         expanded = " ".join(recent) + " " + expanded
 
-    # Encode and score
     query_emb = _encode([expanded])
     scores = np.dot(_phrase_embeddings, query_emb.T).flatten()
 
-    # Get best score per topic (deduped)
     topic_best = {}
     for i, score in enumerate(scores):
         tidx = _phrase_topic_idx[i]
@@ -2936,7 +2793,6 @@ def fallback_reply(user_message):
 
     if best_score < _THRESHOLD:
         _last_query = msg
-        # If follow-up failed, try without history context
         if is_followup:
             bare_expanded = _expand_query(msg)
             query_emb2 = _encode([bare_expanded])
@@ -2955,24 +2811,19 @@ def fallback_reply(user_message):
         else:
             return _DEFAULT_RESPONSE
 
-    # ── Build response ────────────────────────────────────────────
     result = _responses[best_idx]
     has_blend = False
 
-    # Multi-topic blending with smooth transitions
     if len(ranked) >= 2:
         second_idx, second_score = ranked[1]
         gap = best_score - second_score
         if second_score >= _THRESHOLD and gap < 0.07:
-            # Avoid blending if both topics are too similar or same category
             transition = _random.choice(_BLEND_TRANSITIONS)
             result += transition + _responses[second_idx]
             has_blend = True
 
-    # Wrap with conversational framing
     result = _wrap_response(result, best_score, intent, is_followup, has_blend)
 
-    # Update conversation memory
     _last_topic_idx = best_idx
     _last_query = msg
     _conv_history.append((msg, best_idx, best_score))

Backend/cfg/__init__.py

@@ -1,9 +1,3 @@
-# ============================================================================
-# CFG PACKAGE - Context-free grammar + parse table for the GAL parser
-# ============================================================================
-# Re-exports the three public artifacts so `from cfg import cfg, first_sets,
-# predict_sets` keeps working unchanged after the restructure.
-# ============================================================================
 
 from .grammar import (  # noqa: F401
     cfg,

Backend/cfg/grammar.py

@@ -1,73 +1,47 @@
-# ============================================================================
-# CFG GRAMMAR + FIRST/FOLLOW/PREDICT - the static parse table source
-# ============================================================================
-# Extracted from Backend/cfg.py during the modular restructure.
-# Exports three artifacts consumed by parser/parser.py:
-#   cfg           : Dict[non_terminal -> List[List[symbol]]]
-#   first_sets    : Dict[non_terminal -> Set[terminal]]
-#   predict_sets  : Dict[(non_terminal, production) -> Set[terminal]]
-# ============================================================================
 import sys
 from collections import defaultdict
 
-# Set UTF-8 encoding for Windows console (so λ prints correctly during dev)
 if sys.platform == 'win32':
     try:
         sys.stdout.reconfigure(encoding='utf-8')
     except:
         pass
 
-# Use λ (lambda) as epsilon symbol - represents empty/null production
 EPSILON = "λ"
 
 
 def compute_first(cfg):
-    """
-    Compute FIRST sets for all non-terminals in the grammar.
-    
-    FIRST(X) = set of terminals that can appear at the beginning 
-               of any string derived from X
-    
-    Example: If X -> aB, then 'a' is in FIRST(X)
-    """
-    first = defaultdict(set)  # Dictionary to store FIRST sets for each non-terminal
+    first = defaultdict(set)
     epsilon = EPSILON
 
-    # Initial pass: Add terminals and epsilon that appear first in productions
-    for lhs, productions in cfg.items():  # lhs = left-hand side (non-terminal)
-        for prod in productions:  # prod = production (right-hand side)
+    for lhs, productions in cfg.items():
+        for prod in productions:
             if not prod:
                 continue
-            if prod[0] == epsilon:  # Production derives epsilon directly
+            if prod[0] == epsilon:
                 first[lhs].add(epsilon)
-            elif prod[0] not in cfg:  # First symbol is a terminal (not a non-terminal)
+            elif prod[0] not in cfg:
                 first[lhs].add(prod[0])
 
-    # Iterative pass: Keep updating FIRST sets until no changes occur
     changed = True
     while changed:
         changed = False
         for lhs, productions in cfg.items():
             for prod in productions:
-                before = len(first[lhs])  # Track size to detect changes
+                before = len(first[lhs])
 
-                # Process each symbol in the production
                 for symbol in prod:
-                    if symbol in cfg:  # Symbol is a non-terminal
-                        # Add FIRST(symbol) to FIRST(lhs), excluding epsilon
+                    if symbol in cfg:
                         first[lhs] |= (first[symbol] - {epsilon})
-                        # If symbol cannot derive epsilon, stop here
                         if epsilon not in first[symbol]:
                             break
-                    else:  # Symbol is a terminal
+                    else:
                         if symbol != epsilon:
                             first[lhs].add(symbol)
                         break
                 else:
-                    # All symbols can derive epsilon, so this production can too
                     first[lhs].add(epsilon)
 
-                # Check if FIRST set grew
                 if len(first[lhs]) > before:
                     changed = True
 
@@ -75,53 +49,36 @@ def compute_first(cfg):
 
 
 def compute_follow(cfg, first):
-    """
-    Compute FOLLOW sets for all non-terminals in the grammar.
-    
-    FOLLOW(X) = set of terminals that can appear immediately after X
-                in any derivation
-    
-    Example: If S -> AB, then FOLLOW(A) includes FIRST(B)
-    """
-    follow = defaultdict(set)  # Dictionary to store FOLLOW sets
+    follow = defaultdict(set)
     epsilon = EPSILON
 
-    # Start symbol gets end-of-input marker (EOF)
-    start_symbol = next(iter(cfg))  # First non-terminal in grammar
+    start_symbol = next(iter(cfg))
     follow[start_symbol].add("EOF")
 
-    # Iterative pass: Keep updating until no changes
     changed = True
     while changed:
         changed = False
         for lhs, productions in cfg.items():
             for prod in productions:
-                # Check each symbol in the production
                 for i, symbol in enumerate(prod):
-                    if symbol in cfg:  # Only compute FOLLOW for non-terminals
+                    if symbol in cfg:
                         before = len(follow[symbol])
 
-                        # Look at all symbols that come after this symbol
                         j = i + 1
                         while j < len(prod):
                             next_symbol = prod[j]
-                            if next_symbol in cfg:  # Next symbol is non-terminal
-                                # Add FIRST(next_symbol) to FOLLOW(symbol), excluding epsilon
+                            if next_symbol in cfg:
                                 follow[symbol] |= (first[next_symbol] - {epsilon})
-                                # If next symbol cannot derive epsilon, stop here
                                 if epsilon not in first[next_symbol]:
                                     break
-                            else:  # Next symbol is terminal
+                            else:
                                 if next_symbol != epsilon:
                                     follow[symbol].add(next_symbol)
                                 break
                             j += 1
                         else:
-                            # All remaining symbols can derive epsilon (or we reached the end)
-                            # Add FOLLOW(lhs) to FOLLOW(symbol)
                             follow[symbol] |= follow[lhs]
 
-                        # Check if FOLLOW set grew
                         if len(follow[symbol]) > before:
                             changed = True
 
@@ -129,481 +86,353 @@ def compute_follow(cfg, first):
 
 
 def compute_predict(cfg, first, follow):
-    """
-    Compute PREDICT sets for all productions in the grammar.
-    
-    PREDICT(A -> α) = set of terminals that indicate when to use this production
-    
-    Used to build parsing table for predictive (LL) parser:
-    - If next input token is in PREDICT(A -> α), use that production
-    
-    Rules:
-    1. Add FIRST(α) to PREDICT
-    2. If α can derive epsilon, also add FOLLOW(A)
-    """
-    predict = {}  # Dictionary to store PREDICT sets
+    predict = {}
     epsilon = EPSILON
 
     for lhs, productions in cfg.items():
         for prod in productions:
-            # Key is (non-terminal, production tuple)
             key = (lhs, tuple(prod))
             predict[key] = set()
 
-            # Check if production is epsilon (empty or just epsilon symbol)
             if not prod or (len(prod) == 1 and prod[0] == epsilon):
-                # Epsilon production: PREDICT = FOLLOW(lhs)
                 predict[key] = follow[lhs].copy()
                 continue
 
-            # Compute FIRST set of this production
             first_set = set()
             for symbol in prod:
-                if symbol in cfg:  # Symbol is non-terminal
-                    # Add FIRST(symbol) excluding epsilon
+                if symbol in cfg:
                     first_set |= (first[symbol] - {epsilon})
-                    # If symbol cannot derive epsilon, stop
                     if epsilon not in first[symbol]:
                         break
-                else:  # Symbol is terminal
+                else:
                     if symbol != epsilon:
                         first_set.add(symbol)
                     break
             else:
-                # All symbols can derive epsilon
                 first_set.add(epsilon)
 
-            # PREDICT set starts with FIRST set
             predict[key] = first_set
-            # If production can derive epsilon, add FOLLOW(lhs)
             if epsilon in first_set:
                 predict[key] |= follow[lhs] 
 
     return predict
 
 
-# ===============================================================================
-# GAL (Grow A Language) Context-Free Grammar Definition
-# ===============================================================================
-# This dictionary defines the complete grammar for the GAL programming language.
-# Format: { "<non-terminal>": [ [production1], [production2], ... ] }
-# 
-# Non-terminals: Enclosed in < >, represent grammar rules (e.g., <program>)
-# Terminals: Actual tokens from the lexer (e.g., "seed", "id", "{")
-# λ (EPSILON): Represents empty production (optional/nullable rules)
-# ===============================================================================
-
 cfg = {
-    # ===== PROGRAM STRUCTURE =====
-    # Entry point: Every GAL program must have a root() function
     "<program>": [
         [
-            "<global_declaration>",   # Global variables, constants, bundles (structs)
-            "<function_definition>",  # User-defined functions
-            "root",                   # Main function name (like main() in C)
+            "<global_declaration>",
+            "<function_definition>",
+            "root",
             "(",
             ")",
             "{",
-            "<local_declaration>",    # Old-style C local declarations must come first
-            "<body_statement>",       # Executable statements before the required final return
-            "reclaim",                # root() must end with reclaim;
+            "<local_declaration>",
+            "<body_statement>",
+            "reclaim",
             ";",
             "}",
         ]
     ],
 
-    # ===== GLOBAL DECLARATIONS =====
-    # Variables, constants, and structs declared outside functions
     "<global_declaration>": [
-        ["bundle", "id", "<bundle_or_var>", "<global_declaration>"],  # Bundle definition or variable
-        ["<data_type>", "id", "<array_dec>", "<var_value>", ";", "<global_declaration>"],  # Variable declaration
-        ["fertile", "<data_type>", "id", "=", "<init_val>", "<const_next>", ";", "<global_declaration>"],  # Constant declaration
-        [EPSILON],  # Can be empty (no global declarations)
+        ["bundle", "id", "<bundle_or_var>", "<global_declaration>"],
+        ["<data_type>", "id", "<array_dec>", "<var_value>", ";", "<global_declaration>"],
+        ["fertile", "<data_type>", "id", "=", "<init_val>", "<const_next>", ";", "<global_declaration>"],
+        [EPSILON],
     ],
 
-    # Distinguish between bundle definition and bundle variable after seeing "bundle id"
     "<bundle_or_var>": [
-        ["{", "<bundle_members>", "}", ";"],           # Bundle definition: bundle Person { ... };
-        ["<bundle_mem_dec>", ";"],                      # Bundle variable: bundle Person p;
+        ["{", "<bundle_members>", "}", ";"],
+        ["<bundle_mem_dec>", ";"],
     ],
 
-    # ===== LOCAL DECLARATIONS =====
-    # Variables and constants declared inside functions
     "<local_declaration>": [
-        ["<var_dec>", ";", "<local_declaration>"],   # Variable/array/bundle-variable declaration
-        ["<const_dec>", ";", "<local_declaration>"], # Constant declaration
-        [EPSILON],  # Can be empty (no local declarations)
+        ["<var_dec>", ";", "<local_declaration>"],
+        ["<const_dec>", ";", "<local_declaration>"],
+        [EPSILON],
     ],
 
-    # ===== DATA TYPES =====
-    # The five primitive types in GAL
     "<data_type>": [
-        ["seed"],    # Integer type
-        ["tree"],    # Float/Double type
-        ["leaf"],    # Character type
-        ["branch"],  # Boolean type
-        ["vine"],    # String type
+        ["seed"],
+        ["tree"],
+        ["leaf"],
+        ["branch"],
+        ["vine"],
     ],
 
-    # ===== CONSTANT DECLARATIONS =====
-    # Example: fertile seed MAX = 100;
-    #          fertile leaf NEWLINE = '\n', TAB = '\t';
     "<const_dec>": [
         ["fertile", "<data_type>", "id", "=", "<init_val>", "<const_next>"],
     ],
 
     "<const_next>": [
-        [",", "id", "=", "<init_val>", "<const_next>"],  # Multiple constants in one line
-        [EPSILON],  # Single constant
+        [",", "id", "=", "<init_val>", "<const_next>"],
+        [EPSILON],
     ],
 
-    # ===== VARIABLE DECLARATIONS =====
-    # Examples: seed x = 5;
-    #           tree arr[10];
-    #           bundle Person p;
-    #           bundle Person group[2];
     "<var_dec>": [
-        ["<data_type>", "id", "<array_dec>", "<var_value>"],  # Regular variable or array
-        ["bundle", "id", "<bundle_mem_dec>"],                 # Struct variable
+        ["<data_type>", "id", "<array_dec>", "<var_value>"],
+        ["bundle", "id", "<bundle_mem_dec>"],
     ],
 
     "<bundle_mem_dec>": [
-        ["id", "<array_dec>"],  # bundle Person p; or bundle Person p[2];
+        ["id", "<array_dec>"],
     ],
 
     "<var_value>": [
-        ["=", "<init_val>", "<var_value_next>"],  # With initialization: seed x = 1, y = 2;
-        ["<var_value_next>"],                      # Without initialization: seed x, y, z;
+        ["=", "<init_val>", "<var_value_next>"],
+        ["<var_value_next>"],
     ],
 
     "<var_value_next>": [
-        [",", "id", "<array_dec>", "<var_value>"],  # Multiple variables: seed x = 1, y = 2, z;
+        [",", "id", "<array_dec>", "<var_value>"],
         [EPSILON],
     ],
 
-    # ===== INITIALIZATION VALUES =====
     "<init_val>": [
-        ["<array_init_opt>"],                    # Array initialization: seed arr[] = {1, 2, 3};
-        ["water", "(", "<water_arg>", ")"],     # Input: seed x = water(seed);
-        ["<expression>"],                         # Single value: seed x = 5 + 3;
+        ["<array_init_opt>"],
+        ["water", "(", "<water_arg>", ")"],
+        ["<expression>"],
     ],
 
-    # ===== ARRAY DECLARATIONS =====
-    # Examples: seed arr[10];        (1D array - fixed size)
-    #           tree vals[];         (1D array - dynamic size)
-    #           seed matrix[2][3];   (2D array)
-    #           seed cube[2][3][4];  (3D array)
     "<array_dec>": [
-        ["[", "<array_dim_opt>", "]", "<array_dec>"],  # One dimension, possibly more
-        [EPSILON],                                      # Not an array (base case)
+        ["[", "<array_dim_opt>", "]", "<array_dec>"],
+        [EPSILON],
     ],
 
     "<array_dim_opt>": [
-        ["intlit"],  # Size specified: [10]
-        ["dblit"],   # Float size (semantic error)
-        [EPSILON],   # Size not specified: []
+        ["intlit"],
+        ["dblit"],
+        [EPSILON],
     ],
 
-    # ===== ARRAY INITIALIZATION =====
-    # Examples: {1, 2, 3}
-    #           {{1, 2}, {3, 4}}  (nested arrays)
     "<array_init_opt>": [
-        ["{", "<init_vals>", "}"],  # Array initializer
-        [EPSILON],                   # No initialization
+        ["{", "<init_vals>", "}"],
+        [EPSILON],
     ],
 
     "<init_vals>": [
-        ["<init_val_item>", "<init_vals_next>"],  # Start with first item (expression or nested init)
-        [EPSILON],                                 # Empty initializer
+        ["<init_val_item>", "<init_vals_next>"],
+        [EPSILON],
     ],
 
     "<init_vals_next>": [
-        [",", "<init_val_item>", "<init_vals_next>"],  # More items
-        [EPSILON],                                      # End of list
+        [",", "<init_val_item>", "<init_vals_next>"],
+        [EPSILON],
     ],
 
     "<init_val_item>": [
-        ["{", "<init_vals>", "}"],  # Nested initializer
-        ["<expression>"],            # Simple expression
+        ["{", "<init_vals>", "}"],
+        ["<expression>"],
     ],
 
-    # ===== STRUCT (BUNDLE) DECLARATIONS =====
-    # Example: bundle Person {
-    #              seed age;
-    #              branch name;
-    #          }
     "<bundle_members>": [
-        ["<data_type>", "id", ";", "<bundle_members>"],  # Primitive member fields
-        ["id", "id", ";", "<bundle_members>"],            # Nested bundle member: Address addr;
-        [EPSILON],                                        # Empty struct or end of members
+        ["<data_type>", "id", ";", "<bundle_members>"],
+        ["id", "id", ";", "<bundle_members>"],
+        [EPSILON],
     ],
 
-    # ===== FUNCTION DEFINITIONS =====
-    # Example: pollinate seed add(seed a, seed b) {
-    #              reclaim a + b;
-    #          }
     "<function_definition>": [
         [
-            "pollinate",           # Keyword for function definition
-            "<return_type>",       # Return type (seed, tree, leaf, branch, or empty)
-            "id",                  # Function name
+            "pollinate",
+            "<return_type>",
+            "id",
             "(",
-            "<parameters>",        # Parameter list
+            "<parameters>",
             ")",
             "{",
-            "<local_declaration>", # Old-style C local declarations must come first
-            "<body_statement>",    # Executable statements before the required final return
-            "reclaim",             # Every function must end with reclaim
-            "<reclaim_value>",     # Value validated against the declared return type
+            "<local_declaration>",
+            "<body_statement>",
+            "reclaim",
+            "<reclaim_value>",
             "}",
-            "<function_definition>",  # Multiple functions (recursive definition)
+            "<function_definition>",
         ],
-        [EPSILON],  # No more functions
+        [EPSILON],
     ],
 
-    # ===== RETURN TYPE =====
     "<return_type>": [
-        ["<data_type>"],  # Returns seed, tree, leaf, or branch
-        ["empty"],        # Void function (no return value)
-        ["id"],           # User-defined bundle type (e.g., Pair, Person)
+        ["<data_type>"],
+        ["empty"],
+        ["id"],
     ],
 
-    # ===== FUNCTION PARAMETERS =====
-    # Examples: (seed x, tree y)
-    #           ()  (no parameters)
     "<parameters>": [
-        [EPSILON],                      # No parameters
-        ["<param>", "<param_next>"],    # One or more parameters
+        [EPSILON],
+        ["<param>", "<param_next>"],
     ],
 
     "<param>": [
-        ["<data_type>", "id", "<param_array>"],  # Parameter: primitive type + name (optionally array)
-        ["id", "id"],           # Parameter: bundle type + name (e.g., Pair p)
+        ["<data_type>", "id", "<param_array>"],
+        ["id", "id"],
     ],
 
     "<param_array>": [
-        [EPSILON],              # Scalar parameter
-        ["[", "]"],             # Array parameter: seed arr[]
+        [EPSILON],
+        ["[", "]"],
     ],
 
     "<param_next>": [
-        [EPSILON],                           # Last parameter
-        [",", "<param>", "<param_next>"],    # More parameters
+        [EPSILON],
+        [",", "<param>", "<param_next>"],
     ],
 
-    # ===== RETURN STATEMENT =====
-    # Examples: reclaim x + y;
-    #           reclaim;  (for empty functions)
     "<reclaim_value>": [
-        ["<expression>", ";"],  # Return with value
-        [";"],                  # Return without value
+        ["<expression>", ";"],
+        [";"],
     ],
 
-    # ===== STATEMENTS =====
-    # Function/root body statements before the required final reclaim.
-    # Nested blocks still use <statement>, where an early return is legal.
     "<body_statement>": [
         ["<non_reclaim_stmt>", "<body_statement>"],
         [EPSILON],
     ],
 
     "<non_reclaim_stmt>": [
-        ["id", "<id_stmt>"],                     # Assignment, unary, or function call
-        ["<inc_dec_op>", "id", "<id_next>", ";"],# Prefix: ++x; ++arr[i]; ++obj.field;
-        ["<io_stmt>"],                           # water() or plant()
-        ["<conditional_stmt>"],                  # spring/bud/wither
-        ["<loop_stmt>"],                         # grow/cultivate/tend
-        ["<switch_stmt>"],                       # harvest
-        ["<control_stmt>"],                      # prune/skip
+        ["id", "<id_stmt>"],
+        ["<inc_dec_op>", "id", "<id_next>", ";"],
+        ["<io_stmt>"],
+        ["<conditional_stmt>"],
+        ["<loop_stmt>"],
+        ["<switch_stmt>"],
+        ["<control_stmt>"],
     ],
 
-    # A sequence of executable statements (zero or more).
-    # Used for nested blocks, where early reclaim remains allowed.
     "<statement>": [
-        ["<simple_stmt>", "<statement>"],  # One statement followed by more
-        [EPSILON],                         # No more statements (end of block)
+        ["<simple_stmt>", "<statement>"],
+        [EPSILON],
     ],
 
-    # ===== TYPES OF STATEMENTS =====
     "<simple_stmt>": [
-        ["<non_reclaim_stmt>"],           # Regular executable nested statement
-        ["reclaim", "<reclaim_value>"],  # Early return: reclaim x; or reclaim;
+        ["<non_reclaim_stmt>"],
+        ["reclaim", "<reclaim_value>"],
     ],
 
-    # After seeing id, determine what kind of statement it is.
-    # Left-factored so that <id_next> can be followed by either an assignment
-    # operator OR an inc/dec operator — this is what enables arr[i]++; and
-    # obj.field++; (and x++; via <id_next> -> epsilon).
     "<id_stmt>": [
-        ["<id_next>", "<id_stmt_tail>"],     # Assignment OR postfix inc/dec on id/arr[i]/obj.f
-        ["(", "<arguments>", ")", ";"],      # Function call: func();
+        ["<id_next>", "<id_stmt_tail>"],
+        ["(", "<arguments>", ")", ";"],
     ],
 
-    # Tail of <id_stmt>: the operator that follows the (possibly-indexed/
-    # member-accessed) target. Either '=' (or compound '+=' etc.) followed
-    # by an RHS, or a postfix '++' / '--'.
     "<id_stmt_tail>": [
-        ["<assign_op>", "<assign_rhs>", ";"],  # x = 5;  arr[i] = 5;  obj.f += 2;
-        ["<inc_dec_op>", ";"],                  # x++;  arr[i]++;  obj.field--;
+        ["<assign_op>", "<assign_rhs>", ";"],
+        ["<inc_dec_op>", ";"],
     ],
 
-    # ===== ASSIGNMENT STATEMENTS =====
-    # Examples: x = 10;
-    #           arr[0] = 5;
-    #           person.age = 25;
-    #           total += 5;
-    # Assignment right-hand side: either water() input or a regular expression
     "<assign_rhs>": [
-        ["water", "(", "<water_arg>", ")"],  # Input: x = water(seed);
-        ["<expression>"],                      # Expression: x = 5 + 3;
+        ["water", "(", "<water_arg>", ")"],
+        ["<expression>"],
     ],
 
-    # Assignment operators
     "<assign_op>": [
-        ["="],    # Simple assignment
-        ["+="],   # Add and assign
-        ["-="],   # Subtract and assign
-        ["*="],   # Multiply and assign
-        ["/="],   # Divide and assign
-        ["%="],   # Modulo and assign
-        ["**="],  # Exponent and assign (x **= 2  →  x = x ** 2)
+        ["="],
+        ["+="],
+        ["-="],
+        ["*="],
+        ["/="],
+        ["%="],
+        ["**="],
     ],
 
     "<id_next>": [
-        ["<array_access>", "<post_array_access>"],   # Array indexing: arr[0] or arr[0].member
-        ["<struct_access>"],  # Struct member: person.name
-        [EPSILON],            # Just a simple variable: x
+        ["<array_access>", "<post_array_access>"],
+        ["<struct_access>"],
+        [EPSILON],
     ],
 
-    # ===== ARRAY ACCESS =====
-    # Examples: arr[0]
-    #           matrix[i][j]  (multi-dimensional)
     "<array_access>": [
         ["[", "<expression>", "]", "<array_access_more>"],
     ],
 
     "<array_access_more>": [
-        ["[", "<expression>", "]", "<array_access_more>"],  # Additional dimensions
-        [EPSILON],                                           # End of array indexing
+        ["[", "<expression>", "]", "<array_access_more>"],
+        [EPSILON],
     ],
 
-    # ===== STRUCT/BUNDLE ACCESS =====
-    # Examples: person.name
-    #           person.address.city  (nested structs)
     "<struct_access>": [
         [".", "id", "<struct_access_more>"],
     ],
 
     "<struct_access_more>": [
-        [".", "id", "<struct_access_more>"],  # Nested member access
-        [EPSILON],                             # End of member access
+        [".", "id", "<struct_access_more>"],
+        [EPSILON],
     ],
 
-    # Optional struct access after array access (e.g., p[0].x or p[0].addr.zip)
     "<post_array_access>": [
-        [".", "id", "<post_array_access>"],  # Chained member access: p[0].addr.zip
-        [EPSILON],                              # Just array access: arr[0]
+        [".", "id", "<post_array_access>"],
+        [EPSILON],
     ],
 
-    # ===== INPUT/OUTPUT STATEMENTS =====
-    # plant() - output/print function
-    # water() - input/read function
-    # Examples: plant("Hello");
-    #           water();
     "<io_stmt>": [
-        ["plant", "(", "<arguments>", ")", ";"],  # Output: plant("hello")
-        ["water", "(", "<water_arg>", ")", ";"],   # Input standalone: water(); or water(seed);
+        ["plant", "(", "<arguments>", ")", ";"],
+        ["water", "(", "<water_arg>", ")", ";"],
     ],
 
-    # Optional type argument for water()
     "<water_arg>": [
-        ["<data_type>"],                       # Typed input: water(seed), water(tree)
-        ["id", "<water_id_tail>"],             # Variable or list element: water(name) or water(arr[i])
-        [EPSILON],                             # Untyped input: water()
+        ["<data_type>"],
+        ["id", "<water_id_tail>"],
+        [EPSILON],
     ],
 
     "<water_id_tail>": [
-        ["[", "<expression>", "]", "<water_id_tail>"],  # List element: water(arr[i]) or water(arr[i][j])
-        [EPSILON],                             # Plain variable: water(name) / end of indices
+        ["[", "<expression>", "]", "<water_id_tail>"],
+        [EPSILON],
     ],
 
-    # Argument list for function calls and I/O
     "<arguments>": [
-        ["<expression>", "<arg_next>"],  # One or more arguments
-        [EPSILON],                        # No arguments
+        ["<expression>", "<arg_next>"],
+        [EPSILON],
     ],
 
     "<arg_next>": [
-        [",", "<expression>", "<arg_next>"],  # More arguments
-        [EPSILON],                             # Last argument
-    ],
-
-    # ===== CONDITIONAL STATEMENTS =====
-    # spring = if
-    # bud = else if
-    # wither = else
-    # 
-    # Example: spring (x > 0) {
-    #              water("positive");
-    #          }
-    #          bud (x < 0) {
-    #              water("negative");
-    #          }
-    #          wither {
-    #              water("zero");
-    #          }
+        [",", "<expression>", "<arg_next>"],
+        [EPSILON],
+    ],
+
     "<conditional_stmt>": [
         [
-            "spring",              # if keyword
+            "spring",
             "(",
-            "<expression>",        # condition
+            "<expression>",
             ")",
             "{",
-            "<local_declaration>", # Declarations before executable statements
-            "<statement>",         # if body
+            "<local_declaration>",
+            "<statement>",
             "}",
-            "<elseif_chain>",      # else-if chain (optional)
-            "<else_opt>",          # else clause (optional)
+            "<elseif_chain>",
+            "<else_opt>",
         ]
     ],
 
     "<elseif_chain>": [
         [
-            "bud",                 # else-if keyword
+            "bud",
             "(",
-            "<expression>",        # condition
+            "<expression>",
             ")",
             "{",
-            "<local_declaration>", # Declarations before executable statements
-            "<statement>",         # else-if body
+            "<local_declaration>",
+            "<statement>",
             "}",
-            "<elseif_chain>",      # More else-ifs
+            "<elseif_chain>",
         ],
-        [EPSILON],  # No else-if
+        [EPSILON],
     ],
 
     "<else_opt>": [
-        ["wither", "{", "<local_declaration>", "<statement>", "}"],  # else clause
-        [EPSILON],                             # No else
+        ["wither", "{", "<local_declaration>", "<statement>", "}"],
+        [EPSILON],
     ],
 
-    # ===== LOOP STATEMENTS =====
-    # grow = while loop
-    # cultivate = for loop
-    # tend = do-while loop
     "<loop_stmt>": [
-        # While loop: grow (x < 10) { ... }
         ["grow", "(", "<expression>", ")", "{", "<local_declaration>", "<statement>", "}"],
         
-        # For loop: cultivate (seed i = 0; i < 10; i++) { ... }
         [
             "cultivate",
             "(",
-            "<for_init>",          # Initialization
+            "<for_init>",
             ";",
-            "<expression>",        # Condition
+            "<expression>",
             ";",
-            "<for_update>",        # Update
+            "<for_update>",
             ")",
             "{",
             "<local_declaration>",
@@ -611,120 +440,79 @@ cfg = {
             "}",
         ],
         
-        # Do-while: tend { statements } grow ( condition );
         ["tend", "{", "<local_declaration>", "<statement>", "}", "grow", "(", "<expression>", ")", ";"],
     ],
 
     "<for_init>": [
-        ["<data_type>", "id", "<array_dec>", "<var_value>"],  # Variable declaration: seed i = 0
-        ["id", "<id_next>", "<assign_op>", "<expression>"],   # Assignment: i = 0
-        [EPSILON],                                             # Empty initialization
+        ["<data_type>", "id", "<array_dec>", "<var_value>"],
+        ["id", "<id_next>", "<assign_op>", "<expression>"],
+        [EPSILON],
     ],
 
     "<for_update>": [
-        # Left-factored so <id_next> can be followed by EITHER an inc/dec
-        # operator OR an assignment operator. This is what lets
-        # cultivate(...; ...; arr[i]++) and obj.f += 2 work in for-updates.
         ["id", "<id_next>", "<for_update_tail>"],
-        [EPSILON],                                    # Empty update
+        [EPSILON],
     ],
 
     "<for_update_tail>": [
-        ["<inc_dec_op>"],                             # i++  arr[i]++  obj.f--
-        ["<assign_op>", "<expression>"],              # i = i + 1   obj.f += 2
+        ["<inc_dec_op>"],
+        ["<assign_op>", "<expression>"],
     ],
 
-    # ===== UNARY STATEMENTS =====
-    # Examples: x++;  y--;
     "<inc_dec_op>": [
-        ["++"],  # Increment
-        ["--"],  # Decrement
-    ],
-
-    # ===== SWITCH STATEMENT =====
-    # harvest = switch
-    # variety = case
-    # soil = default
-    # prune = break (required after each case)
-    #
-    # Example: harvest (choice) {
-    #              variety (1): water("One"); prune;
-    #              variety (2): water("Two"); prune;
-    #              soil: water("Default");
-    #          }
+        ["++"],
+        ["--"],
+    ],
+
     "<switch_stmt>": [
         ["harvest", "(", "<expression>", ")", "{", "<case_list>", "<default_opt>", "}"],
     ],
 
     "<case_list>": [
         [
-            "variety",             # case keyword
-            "<case_literal>",      # case value (literal only, no expressions)
+            "variety",
+            "<case_literal>",
             ":",
-            "<local_declaration>", # Declarations must precede executable case statements
-            "<case_statements>",   # zero or more executable statements (including prune)
-            "<case_list>",         # More cases
+            "<local_declaration>",
+            "<case_statements>",
+            "<case_list>",
         ],
-        [EPSILON],  # No more cases
+        [EPSILON],
     ],
 
-    # Only literal values are allowed after variety (case)
     "<case_literal>": [
-        ["intlit"],                      # Integer literal (e.g., 1)
-        ["dblit"],                       # Double/float literal (e.g., 3.14)
-        ["chrlit"],                      # Character literal (e.g., 'a')
-        ["stringlit"],                   # String literal (e.g., "hello")
-        ["sunshine"],                    # Boolean true
-        ["frost"],                       # Boolean false
+        ["<literal>"],
     ],
 
-    # Executable statements inside a case - recursive list of statements
     "<case_statements>": [
-        ["<case_statement>", "<case_statements>"],  # One statement, then more
-        [EPSILON],                                  # No more statements (stops at variety/soil/})
+        ["<case_statement>", "<case_statements>"],
+        [EPSILON],
     ],
     
-    # Executable statement types allowed in a case body
     "<case_statement>": [
-        ["id", "<id_stmt>"],                          # Assignment/increment/function call
-        ["<inc_dec_op>", "id", "<id_next>", ";"],     # Prefix: ++x; ++arr[i]; ++obj.f;
-        ["<io_stmt>"],                                # water() or plant()
-        ["<conditional_stmt>"],           # spring (if), bud (else-if), wither (else)
-        ["<loop_stmt>"],                  # grow (while), cultivate (for), tend (do-while)
-        ["<switch_stmt>"],                # harvest (nested switch)
-        ["{", "<local_declaration>", "<statement>", "}"],  # Nested block
-        ["prune", ";"],                   # prune (break)
-        ["skip", ";"],                    # skip (continue)
-        ["reclaim", "<reclaim_value>"],   # Early return: reclaim x; or reclaim;
+        ["id", "<id_stmt>"],
+        ["<inc_dec_op>", "id", "<id_next>", ";"],
+        ["<io_stmt>"],
+        ["<conditional_stmt>"],
+        ["<loop_stmt>"],
+        ["<switch_stmt>"],
+        ["{", "<local_declaration>", "<statement>", "}"],
+        ["prune", ";"],
+        ["skip", ";"],
+        ["reclaim", "<reclaim_value>"],
     ],
 
     "<default_opt>": [
-        ["soil", ":", "<local_declaration>", "<case_statements>"],  # default case
-        [EPSILON],                            # No default
+        ["soil", ":", "<local_declaration>", "<case_statements>"],
+        [EPSILON],
     ],
 
-    # ===== CONTROL FLOW STATEMENTS =====
     "<control_stmt>": [
-        ["prune", ";"],  # break
-        ["skip", ";"],   # continue
-    ],
-
-    # ===== FUNCTION CALL =====
-    # Example: myFunc(x, y, z);
-    # ===== EXPRESSIONS =====
-    # Expressions follow operator precedence (lowest to highest):
-    # 1. Assignment (=, +=, -=, *=, /=, %=), right-associative
-    # 2. Logical OR (||)
-    # 3. Logical AND (&&)
-    # 4. Relational (>, <, >=, <=, ==, !=)
-    # 5. Arithmetic (+, -)
-    # 6. Term (*, /, %)
-    # 7. Power (**)
-    # 8. Factor (literals, variables, function calls, parentheses)
-
-    # Level 1: Assignment expression (lowest precedence).
-    # Semantic analysis verifies that the left side is assignable.
-    # Examples: a = 5, total += amount, a = b = 10
+        ["prune", ";"],
+        ["skip", ";"],
+    ],
+
+
     "<expression>": [
         ["<assignment_expression>"],
     ],
@@ -734,147 +522,118 @@ cfg = {
     ],
 
     "<assignment_expression_next>": [
-        ["<assign_op>", "<assignment_expression>"],  # Right-associative assignment
-        [EPSILON],                                     # Ordinary expression
+        ["<assign_op>", "<assignment_expression>"],
+        [EPSILON],
     ],
 
-    # Level 2: Logical OR
-    # Example: a || b || c
     "<logic_or>": [
         ["<logic_and>", "<logic_or_next>"],
     ],
 
     "<logic_or_next>": [
-        ["||", "<logic_and>", "<logic_or_next>"],  # More OR operations
-        [EPSILON],                                  # End
+        ["||", "<logic_and>", "<logic_or_next>"],
+        [EPSILON],
     ],
 
-    # Level 2: Logical AND
-    # Example: a && b && c
     "<logic_and>": [
         ["<relational>", "<logic_and_next>"],
     ],
 
     "<logic_and_next>": [
-        ["&&", "<relational>", "<logic_and_next>"],  # More AND operations
-        [EPSILON],                                    # End
+        ["&&", "<relational>", "<logic_and_next>"],
+        [EPSILON],
     ],
 
-    # Level 3: Relational operators
-    # Example: a > b, x == y
     "<relational>": [
-        ["<arithmetic>", "<relational_next>"],  # Arithmetic with optional comparison
+        ["<arithmetic>", "<relational_next>"],
     ],
 
     "<relational_next>": [
-        ["<relational_op>", "<arithmetic>"],  # Comparison operator
-        [EPSILON],                             # Just arithmetic, no comparison
+        ["<relational_op>", "<arithmetic>"],
+        [EPSILON],
     ],
 
     "<relational_op>": [
-        [">"],   # Greater than
-        ["<"],   # Less than
-        [">="],  # Greater than or equal
-        ["<="],  # Less than or equal
-        ["=="],  # Equal
-        ["!="],  # Not equal
+        [">"],
+        ["<"],
+        [">="],
+        ["<="],
+        ["=="],
+        ["!="],
     ],
 
-    # Level 4: Arithmetic (addition/subtraction)
-    # Example: a + b - c
     "<arithmetic>": [
         ["<term>", "<arithmetic_next>"],
     ],
 
     "<arithmetic_next>": [
-        ["+", "<term>", "<arithmetic_next>"],  # Addition
-        ["-", "<term>", "<arithmetic_next>"],  # Subtraction
-        ["`", "<term>", "<arithmetic_next>"],  # String concatenation: vine/leaf operands produce vine
-        [EPSILON],                              # End
+        ["+", "<term>", "<arithmetic_next>"],
+        ["-", "<term>", "<arithmetic_next>"],
+        ["`", "<term>", "<arithmetic_next>"],
+        [EPSILON],
     ],
 
-    # String-expression type rules are enforced during semantic analysis:
-    #   vine/leaf ` vine/leaf -> vine
-    #   vine == vine and vine != vine -> branch
-    #   vine cannot be used with <, >, <=, >=, &&, or ||
 
-    # Level 5: Term (multiplication/division/modulo)
-    # Example: a * b / c % d
     "<term>": [
         ["<power>", "<term_next>"],
     ],
 
     "<term_next>": [
-        ["*", "<power>", "<term_next>"],  # Multiplication
-        ["/", "<power>", "<term_next>"],  # Division
-        ["%", "<power>", "<term_next>"],  # Modulo
-        [EPSILON],                          # End
+        ["*", "<power>", "<term_next>"],
+        ["/", "<power>", "<term_next>"],
+        ["%", "<power>", "<term_next>"],
+        [EPSILON],
     ],
 
-    # Level 6: Power (right-associative exponentiation)
-    # Example: a ** b ** c
     "<power>": [
         ["<factor>", "<power_next>"],
     ],
 
     "<power_next>": [
-        ["**", "<power>"],  # Exponentiation
-        [EPSILON],           # End
+        ["**", "<power>"],
+        [EPSILON],
     ],
 
-    # Level 7: Factor (highest precedence - literals, variables, etc.)
     "<factor>": [
-        ["(", "<paren_expr>"],           # Cast or parenthesized expression
-        ["<unary_op>", "<factor>"],      # Unary operation (e.g., ~x, !flag)
-        ["id", "<factor_id_next>"],      # Variable, array, struct, or function
-        ["intlit"],                      # Integer literal (e.g., 42)
-        ["dblit"],                       # Double/float literal (e.g., 3.14)
-        ["chrlit"],                       # Character literal (e.g., 'a')
-        ["stringlit"],                   # String literal (e.g., "hello")
-        ["sunshine"],                    # Boolean true
-        ["frost"],                       # Boolean false
-    ],
-
-    # Disambiguate after '(' — either a type cast or a grouped expression
-    # No LL(1) conflict: FIRST(<data_type>) = {seed,tree,leaf,branch,vine}
-    #                    FIRST(<expression>) = {(,~,!,id,intlit,dblit,...}
+        ["(", "<paren_expr>"],
+        ["<unary_op>", "<factor>"],
+        ["id", "<factor_id_next>"],
+        ["<literal>"],
+    ],
+
+    "<literal>": [
+        ["intlit"],
+        ["dblit"],
+        ["chrlit"],
+        ["stringlit"],
+        ["sunshine"],
+        ["frost"],
+    ],
+
     "<paren_expr>": [
-        ["<data_type>", ")", "<factor>"],  # Type cast: (seed)x, (tree)3.14
-        ["<expression>", ")"],             # Parenthesized expression: (x + 1)
+        ["<data_type>", ")", "<factor>"],
+        ["<expression>", ")"],
     ],
     
-    # Unary operators
     "<unary_op>": [
-        ["~"],   # Arithmetic negation
-        ["!"],   # Logical NOT
+        ["~"],
+        ["!"],
     ],
 
-    # For identifiers in expressions - could be variable, array, struct, or function
     "<factor_id_next>": [
-        ["<array_access>", "<post_array_access>"],  # Array element: arr[0] or arr[0].member
-        ["<struct_access>"],          # Struct member: person.name
-        ["(", "<arguments>", ")"],    # Function call: add(2, 3)
-        [EPSILON],                    # Simple variable: x
+        ["<array_access>", "<post_array_access>"],
+        ["<struct_access>"],
+        ["(", "<arguments>", ")"],
+        [EPSILON],
     ],
 }
 
 
-# ===============================================================================
-# COMPUTE FIRST, FOLLOW, AND PREDICT SETS
-# ===============================================================================
-# These sets are used for building a predictive (LL) parser
-
-
-# Compute the FIRST, FOLLOW, and PREDICT sets
 first_sets = compute_first(cfg)
 follow_sets = compute_follow(cfg, first_sets)
 predict_sets = compute_predict(cfg, first_sets, follow_sets)
 
 
-# ===============================================================================
-# OUTPUT: Display the computed sets (only when run directly)
-# ===============================================================================
-
 if __name__ == '__main__':
     print("=" * 80)
     print("FIRST SETS")

Backend/icg/__init__.py

@@ -1,9 +1,2 @@
-# ============================================================================
-# ICG PACKAGE - Intermediate Code Generation (Three-Address Code, display-only)
-# ============================================================================
-# Re-exports generate_icg so external callers (server.py) can keep using:
-#     from icg import generate_icg
-# unchanged after the restructure.
-# ============================================================================
 
 from .generator import generate_icg, ICGenerator, TACInstruction  # noqa: F401

Backend/icg/generator.py

@@ -1,14 +1,3 @@
-# ============================================================================
-# ICG GENERATOR - Three-Address Code (TAC) generator (display-only)
-# ============================================================================
-# Extracted from Backend/icg.py during the modular restructure.
-# Pipeline position:
-#   lex -> parse -> AST -> semantic -> THIS FILE (display) -> interpret(AST)
-#                                       \________________/
-#                                        parallel pass; not on runtime path
-# The output is a list of quad-like TAC instructions for IDE display.
-# The interpreter walks the AST directly and does NOT consume this output.
-# ============================================================================
 from __future__ import annotations
 from dataclasses import dataclass
 from typing import Any, Dict, List, Optional, Tuple, Union
@@ -23,7 +12,6 @@ class _Tok:
 
 
 def _as_tok(raw: Any) -> _Tok:
-    """Normalise dict / object tokens into a uniform view."""
     if isinstance(raw, dict):
         return _Tok(
             type=str(raw.get("type", "")),
@@ -39,13 +27,8 @@ def _as_tok(raw: Any) -> _Tok:
     )
 
 
-# ---------------------------------------------------------------------------
-# Three-Address Code (TAC) instruction
-# ---------------------------------------------------------------------------
-
 @dataclass
 class TACInstruction:
-    """One three-address code quad."""
     op: str
     arg1: Optional[str] = None
     arg2: Optional[str] = None
@@ -92,7 +75,6 @@ class TACInstruction:
             return f"{self.arg1} = {self.arg1} + 1"
         if self.op == "DEC":
             return f"{self.arg1} = {self.arg1} - 1"
-        # Binary / unary arithmetic & assignment
         if self.arg2 is not None:
             return f"{self.result} = {self.arg1} {self.op} {self.arg2}"
         if self.op == "=":
@@ -113,9 +95,6 @@ class TACInstruction:
         }
 
 
-# ---------------------------------------------------------------------------
-# GAL type map
-# ---------------------------------------------------------------------------
 GAL_TYPE_MAP = {
     "seed": "int",
     "tree": "float",
@@ -130,32 +109,24 @@ DATA_TYPE_TOKENS = set(GAL_TYPE_MAP.keys())
 ASSIGN_OPS = {"=", "+=", "-=", "*=", "/=", "%="}
 
 
-# ---------------------------------------------------------------------------
-# Intermediate Code Generator
-# ---------------------------------------------------------------------------
-
 class ICGenerator:
-    """Generates three-address code from a GAL token stream."""
 
     def __init__(self, tokens: List[Any]):
         self.tokens: List[_Tok] = self._prepare(tokens)
-        self.pos: int = 0               # current position in token stream
-        self.code: List[TACInstruction] = []  # generated TAC
+        self.pos: int = 0
+        self.code: List[TACInstruction] = []
         self.errors: List[str] = []
         self._temp_counter: int = 0
         self._label_counter: int = 0
 
-    # -- helpers ------------------------------------------------------------
 
     def _prepare(self, raw_tokens: List[Any]) -> List[_Tok]:
-        """Normalise and filter (skip newlines)."""
         toks: List[_Tok] = []
         for t in raw_tokens:
             tv = _as_tok(t)
             if tv.type == "\n":
                 continue
             toks.append(tv)
-        # Ensure EOF
         if not toks or toks[-1].type != "EOF":
             last_line = toks[-1].line if toks else 1
             toks.append(_Tok("EOF", "EOF", last_line))
@@ -178,12 +149,10 @@ class ICGenerator:
             self.errors.append(
                 f"ICG Line {tok.line}: expected '{token_type}', got '{tok.type}'"
             )
-            # try to continue anyway
             return tok
         return self._advance()
 
     def _match(self, token_type: str) -> bool:
-        """If current token matches, consume and return True."""
         if self._peek().type == token_type:
             self._advance()
             return True
@@ -206,12 +175,8 @@ class ICGenerator:
     def _is_data_type(self, tok: _Tok) -> bool:
         return tok.type in DATA_TYPE_TOKENS
 
-    # ======================================================================
-    # TOP-LEVEL: <program>
-    # ======================================================================
 
     def generate(self) -> Tuple[List[TACInstruction], List[str]]:
-        """Entry point — generate TAC for the whole program."""
         try:
             self._program()
         except Exception as exc:
@@ -219,11 +184,9 @@ class ICGenerator:
         return self.code, self.errors
 
     def _program(self):
-        """<program> -> ... root ( ) { <local_declaration> <body_statement> reclaim ; }"""
         self._global_declaration()
         self._function_definition()
 
-        # root ( ) { ... }
         self._expect("root")
         self._expect("(")
         self._expect(")")
@@ -240,33 +203,27 @@ class ICGenerator:
         self._expect("}")
         self._emit("ENDFUNC")
 
-    # ======================================================================
-    # GLOBAL DECLARATIONS
-    # ======================================================================
 
     def _global_declaration(self):
-        """<global_declaration> → bundle id ... | <data_type> id ... | fertile ... | λ"""
         while True:
             tok = self._peek()
             if tok.type == "bundle":
-                self._advance()  # bundle
+                self._advance()
                 name_tok = self._expect("id")
                 nxt = self._peek()
                 if nxt.type == "{":
-                    # bundle definition: bundle Id { members }
-                    self._advance()  # {
+                    self._advance()
                     self._bundle_members()
                     self._expect("}")
                     self._expect(";")
                 else:
-                    # bundle variable: bundle Id varName ... ;
                     self._bundle_mem_dec()
                     self._expect(";")
                 self._global_declaration()
                 return
 
             elif self._is_data_type(tok):
-                dtype = self._advance()  # data type
+                dtype = self._advance()
                 id_tok = self._expect("id")
                 arr_dims = self._array_dec()
                 if arr_dims:
@@ -288,15 +245,10 @@ class ICGenerator:
                 return
 
             else:
-                # λ — no more global declarations
                 return
 
-    # ======================================================================
-    # LOCAL DECLARATIONS
-    # ======================================================================
 
     def _declaration(self):
-        """Consume the <local_declaration> prefix of a block."""
         while True:
             tok = self._peek()
             if self._is_data_type(tok) or tok.type == "bundle":
@@ -309,7 +261,6 @@ class ICGenerator:
                 break
 
     def _var_dec(self):
-        """<var_dec> → <data_type> id <array_dec> <var_value> | bundle id <bundle_mem_dec>"""
         tok = self._peek()
         if tok.type == "bundle":
             self._advance()
@@ -317,7 +268,7 @@ class ICGenerator:
             self._bundle_mem_dec()
             return
 
-        dtype = self._advance()  # data type keyword
+        dtype = self._advance()
         id_tok = self._expect("id")
         arr_dims = self._array_dec()
         if arr_dims:
@@ -329,9 +280,8 @@ class ICGenerator:
         self._var_value(id_tok.value)
 
     def _const_dec(self):
-        """fertile <data_type> id = <init_val> <const_next>"""
         self._expect("fertile")
-        dtype = self._advance()  # data type
+        dtype = self._advance()
         id_tok = self._expect("id")
         self._expect("=")
         val = self._init_val()
@@ -339,7 +289,6 @@ class ICGenerator:
         self._const_next(dtype)
 
     def _const_next(self, dtype_tok: _Tok):
-        """<const_next> → , id = <init_val> <const_next> | λ"""
         while self._match(","):
             id_tok = self._expect("id")
             self._expect("=")
@@ -347,9 +296,8 @@ class ICGenerator:
             self._emit("CONST", GAL_TYPE_MAP.get(dtype_tok.type, dtype_tok.type), val, id_tok.value)
 
     def _var_value(self, var_name: str):
-        """<var_value> → = <init_val> <var_value_next> | <var_value_next>"""
         if self._peek().type == "=":
-            self._advance()  # =
+            self._advance()
             val = self._init_val()
             self._emit("=", val, None, var_name)
             self._var_value_next()
@@ -357,7 +305,6 @@ class ICGenerator:
             self._var_value_next()
 
     def _var_value_next(self):
-        """<var_value_next> → , id <array_dec> <var_value> | λ"""
         if self._match(","):
             id_tok = self._expect("id")
             arr_dims = self._array_dec()
@@ -369,13 +316,11 @@ class ICGenerator:
             self._var_value(id_tok.value)
 
     def _init_val(self) -> str:
-        """<init_val> → <array_init_opt> | <expression>"""
         if self._peek().type == "{":
             return self._array_init()
         return self._expression()
 
     def _array_init(self) -> str:
-        """{ <init_vals> }  — emit element-by-element stores, return temp."""
         self._expect("{")
         tmp = self._new_temp()
         idx = 0
@@ -395,31 +340,25 @@ class ICGenerator:
             return self._array_init()
         return self._expression()
 
-    # ======================================================================
-    # ARRAY & STRUCT HELPERS
-    # ======================================================================
 
     def _array_dec(self) -> List[str]:
-        """<array_dec> → [ <array_dim_opt> ] <array_dec> | λ  — returns list of dimension sizes."""
         dims: List[str] = []
         while self._peek().type == "[":
-            self._advance()  # [
+            self._advance()
             if self._peek().type == "intlit":
                 dims.append(self._advance().value)
             else:
-                dims.append("0")  # dynamic / unspecified
+                dims.append("0")
             self._expect("]")
         return dims
 
     def _bundle_members(self):
-        """<bundle_members> → <data_type> id ; <bundle_members> | λ"""
         while self._is_data_type(self._peek()):
             dtype = self._advance()
             id_tok = self._expect("id")
             self._expect(";")
 
     def _bundle_mem_dec(self):
-        """<bundle_mem_dec> → id <array_dec>"""
         id_tok = self._expect("id")
         arr_dims = self._array_dec()
         if arr_dims:
@@ -428,22 +367,16 @@ class ICGenerator:
         else:
             self._emit("DECLARE", "bundle", None, id_tok.value)
 
-    # ======================================================================
-    # FUNCTION DEFINITIONS
-    # ======================================================================
 
     def _function_definition(self):
-        """<function_definition> → pollinate <return_type> id ( <parameters> ) { ... } <function_definition> | λ"""
         while self._peek().type == "pollinate":
-            self._advance()  # pollinate
+            self._advance()
 
-            # return type
             if self._peek().type == "empty":
                 ret_type = self._advance().type
             elif self._is_data_type(self._peek()):
                 ret_type = self._advance().type
             elif self._peek().type == "id":
-                # User-defined bundle type as return type
                 ret_type = self._advance().value
             else:
                 ret_type = "void"
@@ -451,7 +384,6 @@ class ICGenerator:
             func_name = self._expect("id")
             self._expect("(")
 
-            # parameters
             params = self._parameters()
 
             self._expect(")")
@@ -480,7 +412,6 @@ class ICGenerator:
             self._emit("ENDFUNC")
 
     def _parameters(self):
-        """<parameters> → <param> <param_next> | λ"""
         params = []
         if self._is_data_type(self._peek()) or self._peek().type == "id":
             p = self._param()
@@ -493,22 +424,16 @@ class ICGenerator:
     def _param(self) -> Tuple[str, str]:
         dtype = self._advance()
         id_tok = self._expect("id")
-        # For bundle types, dtype.type is "id" — use dtype.value to get the actual type name
         type_name = dtype.value if dtype.type == "id" else dtype.type
-        # Check for array parameter: seed arr[]
         is_array = False
         if self._peek().type == "[":
-            self._advance()  # skip '['
+            self._advance()
             self._expect("]")
             is_array = True
         return (type_name, id_tok.value, is_array)
 
-    # ======================================================================
-    # STATEMENTS
-    # ======================================================================
 
     def _statement(self, allow_reclaim: bool = False):
-        """Consume executable statements; a function's final reclaim is consumed separately."""
         stopping_tokens = {"}", "EOF", "variety", "soil", "prune"}
         while self._peek().type not in stopping_tokens:
             tok = self._peek()
@@ -517,7 +442,6 @@ class ICGenerator:
                     return
                 self._return_stmt()
                 continue
-            # Nested blocks expose their valid declaration prefix here.
             if self._is_data_type(tok) or tok.type == "bundle" or tok.type == "fertile":
                 if tok.type == "fertile":
                     self._const_dec()
@@ -537,7 +461,6 @@ class ICGenerator:
         self._expect(";")
 
     def _simple_stmt(self):
-        """Dispatch on the first token."""
         tok = self._peek()
 
         if tok.type == "id":
@@ -553,20 +476,16 @@ class ICGenerator:
         elif tok.type in ("prune", "skip"):
             self._control_stmt()
         else:
-            # Skip unknown token to avoid infinite loop
             self.errors.append(f"ICG Line {tok.line}: unexpected token '{tok.type}'")
             self._advance()
 
-    # -- id statement -------------------------------------------------------
 
     def _id_stmt(self):
-        """id <id_next> <assign_op> <expression> ;  |  id <inc_dec_op> ;  |  id ( <arguments> ) ;"""
-        id_tok = self._advance()  # id
+        id_tok = self._advance()
         tok = self._peek()
 
-        # Function call
         if tok.type == "(":
-            self._advance()  # (
+            self._advance()
             args = self._arguments()
             self._expect(")")
             self._expect(";")
@@ -576,18 +495,15 @@ class ICGenerator:
             self._emit("CALL", id_tok.value, str(len(args)), tmp)
             return
 
-        # Increment / decrement
         if tok.type in ("++", "--"):
             op_tok = self._advance()
             self._expect(";")
             self._emit("INC" if op_tok.type == "++" else "DEC", id_tok.value)
             return
 
-        # Assignment (possibly with array / struct access on LHS)
         lhs = id_tok.value
         lhs = self._resolve_lhs(lhs)
 
-        # Assign op
         if self._peek().type in ASSIGN_OPS:
             op_tok = self._advance()
             rhs = self._expression()
@@ -596,27 +512,22 @@ class ICGenerator:
             if op_tok.type == "=":
                 self._emit("=", rhs, None, lhs)
             else:
-                # compound assignment: x += e  →  x = x + e
-                base_op = op_tok.type[0]  # +, -, *, /, %
+                base_op = op_tok.type[0]
                 tmp = self._new_temp()
                 self._emit(base_op, lhs, rhs, tmp)
                 self._emit("=", tmp, None, lhs)
         else:
-            # If it doesn't look like anything valid, skip to ;
             self.errors.append(f"ICG Line {tok.line}: unexpected token after id '{id_tok.value}'")
             while self._peek().type not in (";", "}", "EOF"):
                 self._advance()
             self._match(";")
 
     def _resolve_lhs(self, base: str) -> str:
-        """Handle array access [expr] or struct access .id after an identifier for LHS."""
         tok = self._peek()
         if tok.type == "[":
-            # array access
             self._advance()
             idx = self._expression()
             self._expect("]")
-            # possibly multi-dimensional
             while self._peek().type == "[":
                 self._advance()
                 idx2 = self._expression()
@@ -628,7 +539,6 @@ class ICGenerator:
         elif tok.type == ".":
             self._advance()
             member = self._expect("id")
-            # Possibly nested
             chain = f"{base}.{member.value}"
             while self._peek().type == ".":
                 self._advance()
@@ -637,11 +547,9 @@ class ICGenerator:
             return chain
         return base
 
-    # -- I/O ---------------------------------------------------------------
 
     def _io_stmt(self):
-        """water ( args ) ;  |  plant ( args ) ;"""
-        io_tok = self._advance()  # water / plant
+        io_tok = self._advance()
         self._expect("(")
         args = self._arguments()
         self._expect(")")
@@ -650,14 +558,12 @@ class ICGenerator:
         if io_tok.type == "plant":
             for a in args:
                 self._emit("PRINT", a)
-        else:  # water
+        else:
             for a in args:
                 self._emit("READ", None, None, a)
 
-    # -- conditional --------------------------------------------------------
 
     def _conditional_stmt(self):
-        """spring ( <expr> ) { <stmt> } <elseif_chain> <else_opt>"""
         self._expect("spring")
         self._expect("(")
         cond = self._expression()
@@ -675,10 +581,8 @@ class ICGenerator:
         self._emit("GOTO", None, None, end_label)
         self._emit("LABEL", None, None, false_label)
 
-        # elseif chain
         self._elseif_chain(end_label)
 
-        # else opt
         if self._peek().type == "wither":
             self._advance()
             self._expect("{")
@@ -688,9 +592,8 @@ class ICGenerator:
         self._emit("LABEL", None, None, end_label)
 
     def _elseif_chain(self, end_label: str):
-        """bud ( <expr> ) { <stmt> } <elseif_chain>"""
         while self._peek().type == "bud":
-            self._advance()  # bud
+            self._advance()
             self._expect("(")
             cond = self._expression()
             self._expect(")")
@@ -705,7 +608,6 @@ class ICGenerator:
             self._emit("GOTO", None, None, end_label)
             self._emit("LABEL", None, None, next_label)
 
-    # -- loops --------------------------------------------------------------
 
     def _loop_stmt(self):
         tok = self._peek()
@@ -717,7 +619,6 @@ class ICGenerator:
             self._do_while_loop()
 
     def _while_loop(self):
-        """grow ( <expr> ) { <stmt> }"""
         self._expect("grow")
         self._expect("(")
 
@@ -738,11 +639,9 @@ class ICGenerator:
         self._emit("LABEL", None, None, end_label)
 
     def _for_loop(self):
-        """cultivate ( <for_init> ; <expr> ; <for_update> ) { <stmt> }"""
         self._expect("cultivate")
         self._expect("(")
 
-        # init
         self._for_init()
         self._expect(";")
 
@@ -752,13 +651,11 @@ class ICGenerator:
 
         self._emit("LABEL", None, None, start_label)
 
-        # condition
         cond = self._expression()
         self._emit("IFFALSE", cond, None, end_label)
 
         self._expect(";")
 
-        # save update position — we need to emit update *after* body
         update_instrs: List[TACInstruction] = []
         saved_code = self.code
         self.code = update_instrs
@@ -770,14 +667,12 @@ class ICGenerator:
         self._statement(allow_reclaim=True)
         self._expect("}")
 
-        # emit update
         self._emit("LABEL", None, None, update_label)
         self.code.extend(update_instrs)
         self._emit("GOTO", None, None, start_label)
         self._emit("LABEL", None, None, end_label)
 
     def _for_init(self):
-        """<for_init> → <data_type> id <array_dec> <var_value> | id <id_next> <assign_op> <expression> | λ"""
         tok = self._peek()
         if self._is_data_type(tok):
             self._var_dec()
@@ -794,10 +689,8 @@ class ICGenerator:
                     tmp = self._new_temp()
                     self._emit(base_op, lhs, rhs, tmp)
                     self._emit("=", tmp, None, lhs)
-        # else: λ
 
     def _for_update(self):
-        """<for_update> → id <for_update_type> | λ"""
         if self._peek().type == "id":
             id_tok = self._advance()
             tok = self._peek()
@@ -818,7 +711,6 @@ class ICGenerator:
                         self._emit("=", tmp, None, lhs)
 
     def _do_while_loop(self):
-        """tend { <stmt> } grow ( <expr> ) ;"""
         self._expect("tend")
         self._expect("{")
 
@@ -836,10 +728,8 @@ class ICGenerator:
 
         self._emit("IF", cond, None, start_label)
 
-    # -- switch -------------------------------------------------------------
 
     def _switch_stmt(self):
-        """harvest ( <expr> ) { <case_list> <default_opt> }"""
         self._expect("harvest")
         self._expect("(")
         expr = self._expression()
@@ -854,9 +744,8 @@ class ICGenerator:
         self._emit("LABEL", None, None, end_label)
 
     def _case_list(self, switch_expr: str, end_label: str):
-        """variety <expr> : <case_statements> prune ; <case_list> | λ"""
         while self._peek().type == "variety":
-            self._advance()  # variety
+            self._advance()
             case_val = self._expression()
             self._expect(":")
 
@@ -868,11 +757,9 @@ class ICGenerator:
             self._emit("IFFALSE", cmp_tmp, None, next_label)
             self._emit("LABEL", None, None, body_label)
 
-            # case-local declarations, followed by executable case statements
             self._declaration()
             self._case_statements()
 
-            # prune ;
             if self._peek().type == "prune":
                 self._advance()
                 self._expect(";")
@@ -881,7 +768,6 @@ class ICGenerator:
             self._emit("LABEL", None, None, next_label)
 
     def _case_statements(self):
-        """<case_statements> → <case_statement> <case_statements> | λ"""
         while self._peek().type not in ("variety", "soil", "}", "prune", "EOF"):
             tok = self._peek()
             if tok.type == "id":
@@ -893,36 +779,29 @@ class ICGenerator:
             elif tok.type == "skip":
                 self._advance()
                 self._expect(";")
-                # skip = continue, emit as nop in switch context
             elif tok.type == "reclaim":
                 self._return_stmt()
             else:
                 break
 
     def _default_opt(self, end_label: str):
-        """soil : <local_declaration> <case_statements> | epsilon"""
         if self._peek().type == "soil":
             self._advance()
             self._expect(":")
             self._declaration()
             self._case_statements()
 
-    # -- control (break, continue) ------------------------------------------
 
     def _control_stmt(self):
-        tok = self._advance()  # prune or skip
+        tok = self._advance()
         self._expect(";")
         if tok.type == "prune":
-            self._emit("GOTO", None, None, "BREAK")   # placeholder; real label resolved later
+            self._emit("GOTO", None, None, "BREAK")
         else:
             self._emit("GOTO", None, None, "CONTINUE")
 
-    # ======================================================================
-    # EXPRESSIONS  (precedence climbing, matching the CFG)
-    # ======================================================================
 
     def _expression(self) -> str:
-        """Parse assignment as the lowest-precedence, right-associative expression."""
         left = self._logic_or()
         if self._peek().type not in ASSIGN_OPS:
             return left
@@ -938,7 +817,6 @@ class ICGenerator:
         return left
 
     def _logic_or(self) -> str:
-        """<logic_or> → <logic_and> <logic_or_next>"""
         left = self._logic_and()
         while self._peek().type == "||":
             self._advance()
@@ -949,7 +827,6 @@ class ICGenerator:
         return left
 
     def _logic_and(self) -> str:
-        """<logic_and> → <relational> <logic_and_next>"""
         left = self._relational()
         while self._peek().type == "&&":
             self._advance()
@@ -960,7 +837,6 @@ class ICGenerator:
         return left
 
     def _relational(self) -> str:
-        """<relational> → <arithmetic> <relational_next>"""
         left = self._arithmetic()
         if self._peek().type in (">", "<", ">=", "<=", "==", "!="):
             op = self._advance().type
@@ -971,7 +847,6 @@ class ICGenerator:
         return left
 
     def _arithmetic(self) -> str:
-        """<arithmetic> → <term> <arithmetic_next>"""
         left = self._term()
         while self._peek().type in ("+", "-"):
             op = self._advance().type
@@ -982,7 +857,6 @@ class ICGenerator:
         return left
 
     def _term(self) -> str:
-        """<term> → <factor> <term_next>"""
         left = self._power()
         while self._peek().type in ("*", "/", "%"):
             op = self._advance().type
@@ -1003,17 +877,14 @@ class ICGenerator:
         return left
 
     def _factor(self) -> str:
-        """<factor> → ( <expr> ) | <unary_op> <factor> | id ... | literal"""
         tok = self._peek()
 
-        # ( expression )
         if tok.type == "(":
             self._advance()
             val = self._expression()
             self._expect(")")
             return val
 
-        # Unary: ~ or !
         if tok.type in ("~", "!"):
             op = self._advance()
             inner = self._factor()
@@ -1024,12 +895,10 @@ class ICGenerator:
                 self._emit("NOT", inner, None, tmp)
             return tmp
 
-        # Identifier (variable, array, struct, or function call)
         if tok.type == "id":
             id_tok = self._advance()
             nxt = self._peek()
 
-            # Function call in expression
             if nxt.type == "(":
                 self._advance()
                 args = self._arguments()
@@ -1040,12 +909,10 @@ class ICGenerator:
                 self._emit("CALL", id_tok.value, str(len(args)), tmp)
                 return tmp
 
-            # Array access
             if nxt.type == "[":
                 self._advance()
                 idx = self._expression()
                 self._expect("]")
-                # multi-dim
                 while self._peek().type == "[":
                     self._advance()
                     idx2 = self._expression()
@@ -1060,7 +927,6 @@ class ICGenerator:
                 self._emit("ARRAY_LOAD", id_tok.value, idx, tmp)
                 return tmp
 
-            # Struct access
             if nxt.type == ".":
                 self._advance()
                 member = self._expect("id")
@@ -1076,10 +942,8 @@ class ICGenerator:
                 self._emit("STRUCT_LOAD", id_tok.value, chain, tmp)
                 return tmp
 
-            # Simple variable
             return id_tok.value
 
-        # Literals
         if tok.type == "intlit":
             return self._advance().value
         if tok.type == "dbllit":
@@ -1095,15 +959,12 @@ class ICGenerator:
             self._advance()
             return "false"
 
-        # Fallback
         self.errors.append(f"ICG Line {tok.line}: unexpected token in expression: '{tok.type}'")
         self._advance()
         return "???"
 
-    # -- arguments ----------------------------------------------------------
 
     def _arguments(self) -> List[str]:
-        """<arguments> → <expression> <arg_next> | λ"""
         args: List[str] = []
         if self._peek().type in (")", "EOF"):
             return args
@@ -1113,19 +974,7 @@ class ICGenerator:
         return args
 
 
-# ===========================================================================
-# Public API
-# ===========================================================================
-
 def generate_icg(tokens: List[Any]) -> Dict[str, Any]:
-    """
-    Main entry point for intermediate code generation.
-    Returns a dict with:
-      - 'success': bool
-      - 'tac': list of TAC instruction dicts
-      - 'tac_text': human-readable TAC string
-      - 'errors': list of error strings
-    """
     gen = ICGenerator(tokens)
     code, errors = gen.generate()
 

Backend/interpreter/__init__.py

@@ -1,11 +1,3 @@
-# ============================================================================
-# INTERPRETER PACKAGE - Public API for the runtime execution phase
-# ============================================================================
-# Re-exports the Interpreter class and the runtime exception types so
-# external callers (server.py) can keep using:
-#     from interpreter import Interpreter, InterpreterError, _CancelledError
-# unchanged after the restructure.
-# ============================================================================
 
 from .interpreter import Interpreter  # noqa: F401
 from .errors import (  # noqa: F401 - convenience re-exports

Backend/interpreter/errors.py

@@ -1,28 +1,16 @@
-# ============================================================================
-# RUNTIME / INTERPRETER ERRORS - Raised by the tree-walking interpreter
-# ============================================================================
-# Lives with the interpreter because these are pure runtime concerns:
-#   - ReturnValue      : control-flow unwind for `reclaim <expr>;`
-#   - _CancelledError  : raised when the user starts a new run mid-execution
-#   - InterpreterError : standard runtime error (division by zero, etc.)
-#   - InterpreterInputRequest : raised when water() needs input from the client
-# ============================================================================
 
 
 class ReturnValue(Exception):
-    """Raised by 'reclaim <expr>;' to unwind out of a function with a value."""
 
     def __init__(self, value):
         self.value = value
 
 
 class _CancelledError(Exception):
-    """Raised when an interpreter is cancelled mid-execution."""
     pass
 
 
 class InterpreterError(Exception):
-    """All runtime errors raised by the interpreter inherit from this."""
 
     def __init__(self, message, line):
         super().__init__(message)
@@ -36,7 +24,6 @@ class InterpreterError(Exception):
 
 
 class InterpreterInputRequest(Exception):
-    """Carries a prompt up the call stack when water() needs input."""
 
     def __init__(self, prompt, line):
         self.prompt = prompt

Backend/interpreter/interpreter.py

@@ -1,44 +1,12 @@
-# ============================================================================
-# INTERPRETER - Tree-walking executor for the validated AST
-# ============================================================================
-# Extracted from Backend/GALinterpreter.py during the modular restructure.
-# Pipeline position:
-#   lex -> parse -> AST -> semantic -> ICG (display) -> THIS FILE (execute)
-# ============================================================================
-
-# ============================================================================
-# GAL INTERPRETER - Tree-walking executor for the semantic AST
-# ============================================================================
-# This is the runtime engine of the GAL compiler. It walks the AST produced
-# by GALsemantic and executes each node directly. The interpreter does NOT
-# consume the ICG output — TAC is a parallel display layer; execution happens
-# here on the AST.
-#
-# Pipeline position:
-#   lex -> parse -> AST -> semantic -> ICG (display) -> THIS FILE (execute)
-#
-# Output is sent via self.socketio.emit('output', ...) which can be either
-# a real Socket.IO instance (live mode) or an OutputCollector (synchronous).
-# Input is collected via self.socketio.emit('input_required', ...) which
-# parks the interpreter until provide_input() is called.
-# ============================================================================
-
-# ============================================================================
-# IMPORTS - AST node classes from the semantic analyzer + concurrency
-# primitives for cooperative input-waiting.
-# ============================================================================
-from shared.ast_nodes import *  # AST node classes
+
+
+from shared.ast_nodes import *
 
 import threading
 import sys
 
-# Allow deeply recursive GAL programs (e.g. recursive pollinate functions)
-# without hitting Python's default recursion limit (1000)
 sys.setrecursionlimit(10000)
 
-# Prefer eventlet's cooperative Event so wait_for_input yields to the
-# eventlet hub instead of blocking the entire event loop.
-# Falls back to threading.Event if eventlet isn't installed (e.g. in tests).
 try:
     import eventlet.event as _ev
     _USE_EVENTLET = True
@@ -46,11 +14,6 @@ except ImportError:
     _USE_EVENTLET = False
 
 
-# ============================================================================
-# EXCEPTION CLASSES - All extracted to errors.py during the restructure.
-# Re-exported here so existing `from GALinterpreter import InterpreterError, ...`
-# imports keep working unchanged.
-# ============================================================================
 from semantic.errors import SemanticError  # noqa: F401 - some runtime checks raise it
 from interpreter.errors import (  # noqa: F401 - runtime-specific error classes
     ReturnValue,
@@ -59,57 +22,31 @@ from interpreter.errors import (  # noqa: F401 - runtime-specific error classes
     InterpreterInputRequest,
 )
 
-# ============================================================================
-# INTERPRETER CLASS - Tree-walks the AST and executes each node
-# ============================================================================
-# State organization:
-#   - self.scopes      : stack of scope dicts (innermost on top); enter_scope
-#                        pushes a fresh dict, exit_scope pops it
-#   - self.variables   : globals (visible from every scope)
-#   - self.functions   : pollinate definitions, keyed by function name
-#   - self.bundle_types: bundle (struct) layouts
-#   - self.loop_stack  : current loop nesting, used by prune/skip
-#   - self.break_flag  : 'prune' was hit, propagate up to nearest loop/switch
-#   - self.continue_flag: 'skip' was hit, propagate up to nearest loop
-#   - self.input_*     : channels for water() input arriving from the client
-#   - self.socketio    : adapter for output/input I/O (SessionEmitter or
-#                        OutputCollector — both expose .emit())
-# ============================================================================
 class Interpreter:
     def __init__(self, socketio=None):
-        # ---- Output state ----
-        self.output = []                # legacy collector, kept for compat
-        self.socketio = socketio        # plant() uses this to emit 'output'
-
-        # ---- Control-flow flags (set by break/continue, cleared by loops) ----
-        self.loop_stack = []            # nested loop-type strings
-        self.break_flag = False         # set by 'prune'
-        self.continue_flag = False      # set by 'skip'
-
-        # ---- Input plumbing for water() ----
-        self.input_required = False     # True while waiting for the client
-        self.input_events = {}          # var_name -> Event (eventlet/threading)
-        self.input_values = {}          # var_name -> string typed by client
-
-        # ---- Diagnostics ----
-        self.current_node = None        # node being interpreted (for error msgs)
+        self.output = []
+        self.socketio = socketio
+
+        self.loop_stack = []
+        self.break_flag = False
+        self.continue_flag = False
+
+        self.input_required = False
+        self.input_events = {}
+        self.input_values = {}
+
+        self.current_node = None
         self.current_parent = None
 
-        # ---- Symbol tables ----
-        self.variables = {}             # global variables (visible everywhere)
-        self.global_variables = {}      # mirror used by declare_variable for dup-check
-        self.functions = {}             # pollinate definitions (name -> info)
-        self.scopes = [{}]              # scope stack; [0] is the global scope
-        self.current_func_name = None   # name of the function currently executing
-        self.function_variables = {}    # per-function locals (legacy, partially unused)
-        self.bundle_types = {}          # bundle (struct) layouts
-
-
-    # ========================================================================
-    # VARIABLE MANAGEMENT - declare / lookup / set
-    # Lookup walks the scope stack from innermost outward, then falls back to
-    # globals. This implements lexical scoping for the AST walker.
-    # ========================================================================
+        self.variables = {}
+        self.global_variables = {}
+        self.functions = {}
+        self.scopes = [{}]
+        self.current_func_name = None
+        self.function_variables = {}
+        self.bundle_types = {}
+
+
     def declare_variable(self, name, type_, value=None, is_list=False, is_fertile=False):
         scope = self.scopes[-1]
         current_func = self.current_func_name
@@ -135,7 +72,6 @@ class Interpreter:
             self.global_variables[name] = self.variables[name]
         
 
-
     def lookup_variable(self, name):
         for i, scope in enumerate(reversed(self.scopes)):
             if name in scope:
@@ -156,14 +92,8 @@ class Interpreter:
         return f"Semantic Error: Variable '{name}' not declared in any scope."
 
 
-    # ========================================================================
-    # FUNCTION MANAGEMENT - declare / lookup
-    # GAL functions are first registered (when the parser walks pollinate
-    # declarations) and then invoked by name from eval_function_call.
-    # ========================================================================
     def declare_function(self, name, return_type, params, node=None):
         if name in self.functions:
-            # Returns an error string — caller decides whether to raise
             return f"Semantic Error: Function '{name}' already declared."
         self.functions[name] = {"return_type": return_type, "params": params, "node": node}
 
@@ -173,22 +103,14 @@ class Interpreter:
         return f"Semantic Error: Function '{name}' is not defined."
 
 
-    # ========================================================================
-    # SCOPE MANAGEMENT - enter / exit
-    # Each function call, block, and loop body pushes a fresh scope onto
-    # self.scopes. Variables declared inside go in the top dict and vanish
-    # when the scope is popped.
-    # ========================================================================
     def enter_scope(self):
         self.scopes.append({})
 
 
     def exit_scope(self):
-        # Never pop the global scope (scopes[0])
         if len(self.scopes) > 1:
             self.scopes.pop()
 
-        # Clear function-local cache if we're leaving a function call
         if self.current_func_name:
             current_func = self.current_func_name
 
@@ -196,11 +118,6 @@ class Interpreter:
                 self.function_variables[current_func].clear()
 
 
-    # ========================================================================
-    # MAIN AST DISPATCH - The 'switch' that maps each AST-node class to its
-    # eval_* handler. This is the entry point of execution; server.py calls
-    # interp.interpret(ast) where ast is a ProgramNode.
-    # ========================================================================
     def interpret(self, node):
         if isinstance(node, ProgramNode):
             return self.eval_program(node)
@@ -294,31 +211,20 @@ class Interpreter:
         else:
             raise Exception(f"Unknown AST node type: {node.node_type}")
 
-    # ========================================================================
-    # PROGRAM ENTRY - Walks every top-level declaration (globals, fertile,
-    # bundle, pollinate functions) and then synthesizes a call to root().
-    # This implements GAL's rule that root() is always the entry point.
-    # ========================================================================
     def eval_program(self, node):
-        # 1. Process every top-level node (registers globals + functions)
         for child in node.children:
             self.interpret(child)
 
-        # 2. Now invoke root() — the program's entry point
         main_call = FunctionCallNode("root", [], node.line)
         return self.interpret(main_call)
 
 
-    # ========================================================================
-    # DECLARATIONS - variables, bundles, members, fertile (constants)
-    # ========================================================================
     def eval_variable_declaration(self, node):
         var_type = node.children[0].value
         var_name = node.children[1].value
         value_node = node.children[2] if len(node.children) > 2 else None
         is_list = False
         
-        # Default values for uninitialized variables
         default_values = {
             "seed": 0,
             "tree": 0.0,
@@ -331,7 +237,6 @@ class Interpreter:
             if value_node.node_type == "List":
                 value = []
                 if var_type in self.bundle_types:
-                    # Bundle array: initialize list of dicts with default member values (recursive for nested)
                     for _ in value_node.children:
                         value.append(self._build_bundle_defaults(var_type))
                 else:
@@ -380,22 +285,17 @@ class Interpreter:
                         else:
                             value = True
         else:
-            # Uninitialized variable — use default value for the type
             if var_type in self.bundle_types:
-                # Bundle variable: initialize with dict of default member values (recursive for nested)
                 value = self._build_bundle_defaults(var_type)
             else:
                 value = default_values.get(var_type, None)
                     
-        #print(f"\nDeclaring variable '{var_name}' of type '{var_type}' with initial value: {value}")
         self.declare_variable(var_name, var_type, value, is_list=is_list)
 
     def eval_bundle_definition(self, node):
-        """Store bundle type definition for later use."""
         self.bundle_types[node.bundle_name] = node.members
 
     def _build_bundle_defaults(self, bundle_type_name):
-        """Recursively build default values for a bundle type, including nested bundles."""
         _member_defaults = {"seed": 0, "tree": 0.0, "leaf": '', "vine": "", "branch": False}
         members = self.bundle_types[bundle_type_name]
         result = {}
@@ -407,18 +307,14 @@ class Interpreter:
         return result
 
     def eval_member_access(self, node):
-        """Read a bundle member value: p.age or p.addr.zip (nested)"""
         obj_child = node.children[0]
         member_name = node.children[1].value
 
         if obj_child.node_type == "MemberAccess":
-            # Nested: evaluate inner member access first
             bundle_value = self.eval_member_access(obj_child)
         elif obj_child.node_type == "ArrayMemberAccess":
-            # Chained after array member: p[0].addr.zip
             bundle_value = self.eval_array_member_access(obj_child)
         else:
-            # Simple: obj_child is ASTNode("Object", var_name)
             obj_name = obj_child.value
             var_info = self.lookup_variable(obj_name)
             if isinstance(var_info, str):
@@ -432,7 +328,6 @@ class Interpreter:
         return bundle_value[member_name]
 
     def eval_array_member_access(self, node):
-        """Read a bundle array element member value: p[0].x"""
         list_access_node = node.children[0]
         member_name = node.children[1].value
         bundle_element = self.eval_list_access(list_access_node)
@@ -450,16 +345,6 @@ class Interpreter:
         self.declare_variable(var_name, var_type, value, is_list=False,  is_fertile=True)
 
 
-    # ========================================================================
-    # ASSIGNMENT - The biggest dispatch in this file. Handles every shape:
-    #   x = expr;            (simple variable)
-    #   arr[i] = expr;       (single-dim list element)
-    #   arr[i][j] = expr;    (multi-dim list element)
-    #   bundle.member = expr;(struct member)
-    #   x += expr; etc.      (compound assignment operators)
-    # Type-checking against the variable's declared type happens here too.
-    # Returning the stored value lets the same node serve as an expression.
-    # ========================================================================
     def eval_assignment(self, node):
         target_node = node.children[0]
         value_node = node.children[1]
@@ -475,7 +360,6 @@ class Interpreter:
                 return
 
         if target_node.node_type == "ListAccess":
-            # Collect all index nodes from outermost to innermost
             indices = []
             current = target_node
             while hasattr(current, 'node_type') and current.node_type == "ListAccess":
@@ -483,10 +367,8 @@ class Interpreter:
                 if not isinstance(idx, int):
                     raise InterpreterError(f"Runtime Error: List index must be an integer. Got '{idx}'", node.line)
                 indices.append(idx)
-                # children[0] is ASTNode("ListName", name_or_node)
                 current = current.children[0].value
 
-            # current is now the base variable name (string)
             list_name = current
             list_entry = self.lookup_variable(list_name)
             if isinstance(list_entry, str):
@@ -496,7 +378,6 @@ class Interpreter:
             if not isinstance(list_value, (list, str)):
                 raise InterpreterError(f"Runtime Error: Variable '{list_name}' is not a list.", node.line)
 
-            # Handle string element assignment (vine)
             if isinstance(list_value, str):
                 if len(indices) != 1:
                     raise InterpreterError(f"Runtime Error: Multi-dimensional indexing not supported for strings.", node.line)
@@ -508,10 +389,8 @@ class Interpreter:
                 list_value = list_value[:final_idx] + value + list_value[final_idx + 1:]
                 list_entry["value"] = list_value
             else:
-                # indices were collected outermost-first, reverse to get innermost-first
                 indices.reverse()
 
-                # Navigate to the correct nested list
                 target = list_value
                 for i, idx in enumerate(indices[:-1]):
                     if idx < 0 or idx >= len(target):
@@ -527,19 +406,15 @@ class Interpreter:
                 target[final_idx] = value
 
         elif target_node.node_type == "MemberAccess":
-            # Bundle member assignment: p.age = 19 or p.addr.zip = 1000
-            # Collect the chain of member names from outermost to innermost
             chain = []
             current = target_node
             while hasattr(current, 'node_type') and current.node_type == "MemberAccess":
-                chain.append(current.children[1].value)  # member name
-                current = current.children[0]  # go deeper
+                chain.append(current.children[1].value)
+                current = current.children[0]
 
-            chain.reverse()  # now ordered from root to leaf
+            chain.reverse()
 
-            # current is now ASTNode("Object", var_name) or an ArrayMemberAccessNode
             if hasattr(current, 'node_type') and current.node_type == "ArrayMemberAccess":
-                # Chained off array member: p[0].addr.zip = 1000
                 bundle_value = self.interpret(current)
                 if not isinstance(bundle_value, dict):
                     raise InterpreterError(f"Runtime Error: Value is not a bundle.", node.line)
@@ -552,7 +427,6 @@ class Interpreter:
                 if not isinstance(bundle_value, dict):
                     raise InterpreterError(f"Runtime Error: Variable '{obj_name}' is not a bundle.", node.line)
 
-            # Navigate to the parent dict (all but last member)
             for member in chain[:-1]:
                 if member not in bundle_value:
                     raise InterpreterError(f"Runtime Error: Bundle has no member '{member}'.", node.line)
@@ -564,10 +438,8 @@ class Interpreter:
             if final_member not in bundle_value:
                 raise InterpreterError(f"Runtime Error: Bundle has no member '{final_member}'.", node.line)
 
-            # Type coercion: find the final member's declared type
             type_chain_current = current
             if hasattr(type_chain_current, 'node_type') and type_chain_current.node_type == "ArrayMemberAccess":
-                # For array member chains, walk up to find the variable's bundle type
                 la_node = type_chain_current.children[0]
                 while hasattr(la_node, 'node_type') and la_node.node_type == "ListAccess":
                     la_node = la_node.children[0].value
@@ -578,7 +450,6 @@ class Interpreter:
                 var_type = var_info["type"] if not isinstance(var_info, str) else None
 
             if var_type and var_type in self.bundle_types:
-                # Walk through the type definitions to find the final member type
                 cur_type = var_type
                 for member in chain:
                     if cur_type in self.bundle_types:
@@ -593,7 +464,6 @@ class Interpreter:
             bundle_value[final_member] = value
 
         elif target_node.node_type == "ArrayMemberAccess":
-            # Bundle array member assignment: p[0].x = 1
             list_access_node = target_node.children[0]
             member_name = target_node.children[1].value
             bundle_element = self.eval_list_access(list_access_node)
@@ -602,7 +472,6 @@ class Interpreter:
             if member_name not in bundle_element:
                 raise InterpreterError(f"Runtime Error: Bundle has no member '{member_name}'.", node.line)
 
-            # Type coercion for the member
             current = list_access_node
             while hasattr(current, 'node_type') and current.node_type == "ListAccess":
                 current = current.children[0].value
@@ -636,26 +505,15 @@ class Interpreter:
                 value = True if value != 0 else False
 
             self.set_variable(var_name, value)
-            #print(f"\nUpdating variable '{var_name}' of type '{var_type}' with value: {value}")
 
         return value
 
 
-    # ========================================================================
-    # BINARY OPERATIONS - + - * / % ** == != < <= > >= && || `
-    # The biggest expression evaluator. Each operator branch coerces non-
-    # numeric operands (bool, str) into numeric form before computing, so
-    # mixed-type expressions don't crash. The `(backtick) operator handles
-    # vine concatenation specially (BEFORE _parse_literal) to preserve
-    # whitespace-only strings like " ".
-    # ========================================================================
     def eval_binary_op(self, node):
         left = self.interpret(node.children[0])
         right = self.interpret(node.children[1])
         operator = node.value
 
-        # Handle string concatenation with ` before _parse_literal
-        # to preserve whitespace-only vine values like " "
         if operator == '`':
             result = str(left) + str(right)
             return result
@@ -819,12 +677,6 @@ class Interpreter:
         except ZeroDivisionError:
             raise InterpreterError("Runtime Error: Division by zero", "")
 
-    # ========================================================================
-    # _PARSE_LITERAL - Converts a token's string value into the right Python
-    # type. Handles GAL's negative-number prefix '~' (e.g. '~5' -> -5), the
-    # boolean keywords sunshine/frost, and ints / floats / strings / chars.
-    # Called from inside eval_binary_op before doing arithmetic.
-    # ========================================================================
     def _parse_literal(self, value):
 
         if isinstance(value, str):
@@ -851,7 +703,6 @@ class Interpreter:
         if value in ('false', 'frost'):
             return False
 
-        # Handle GAL negative literals: ~20 → -20, ~3.14 → -3.14
         parse_value = value
         if parse_value.startswith('~'):
             parse_value = '-' + parse_value[1:]
@@ -864,11 +715,6 @@ class Interpreter:
             return value 
     
 
-    # ========================================================================
-    # FUNCTION DECLARATION - Registers a 'pollinate' function so it can be
-    # called later. This walks the parameter list and saves the function
-    # body node for the actual call to interpret.
-    # ========================================================================
     def eval_function_declaration(self, node):
         return_type = node.children[0].value
         parameters_node = node.children[1]
@@ -888,41 +734,23 @@ class Interpreter:
 
         return None
 
-    # ========================================================================
-    # BLOCK EXECUTION - Walks the children of a block { ... } in order,
-    # short-circuiting if a break (prune) or continue (skip) was triggered.
-    # ========================================================================
     def eval_block(self, block_node):
         for statement in block_node.children:
             self.interpret(statement)
-            # 'prune' was hit somewhere inside — stop executing this block
             if self.break_triggered():
                 return
-            # 'skip' was hit — also stop; the surrounding loop handles re-entry
             if self.continue_flag:
                 return
 
 
-    # ========================================================================
-    # OUTPUT - 'plant' primitive. Routes to socketio.emit so output is
-    # delivered to the right client (live mode) or collected (sync mode).
-    # ========================================================================
     def plant(self, value):
-        """GAL output primitive."""
         self.socketio.emit('output', {'output': str(value)})
 
-    # Backward-compatible alias kept for older internal callers
     def plant_out(self, num):
         self.socketio.emit('output', {'output': str(num)})
         self.output.append(str(num))
 
 
-    # ========================================================================
-    # PRINT STATEMENT - Implements plant("template", arg1, arg2, ...).
-    # If the first argument is a string with {} placeholders, it formats
-    # the rest into the template (Python str.format style). Otherwise
-    # arguments are joined with spaces (C printf style).
-    # ========================================================================
     def eval_print(self, node):
         if not node.children:
             return
@@ -957,7 +785,6 @@ class Interpreter:
             self.plant(output_str)
             return
 
-        # No {} placeholders — print all arguments separated by spaces (C-style)
         if len(node.children) > 1:
             parts = [str(evaluated_first)]
             for arg in node.children[1:]:
@@ -972,17 +799,11 @@ class Interpreter:
 
         self.plant(str(evaluated_first))
 
-    # ========================================================================
-    # FORMATTED STRING - Strips outer quotes and converts escape sequences
-    # (\n, \t, \", \{, \}, \/, \\) into their real characters before the
-    # string is used as a plant() template.
-    # ========================================================================
     def eval_formatted_string(self, node):
         value = node.value
         if value.startswith('"') and value.endswith('"'):
             value = value[1:-1]
 
-        # Escape sequences
         value = value.replace(r'\\', '\\')
         value = value.replace(r'\n', '\n')
         value = value.replace(r'\t', '\t')
@@ -993,13 +814,7 @@ class Interpreter:
         return value
 
 
-    # ========================================================================
-    # LIST ACCESS - arr[index] reads. Validates bounds and that the index
-    # is an integer. NOTE: indexing is 0-based in the implementation, even
-    # though the GAL spec describes 1-based arrays.
-    # ========================================================================
     def eval_list_access(self, node):
-        # children[0] is ASTNode("ListName", list_name) where list_name is a string or ListAccessNode
         name_or_node = node.children[0].value
         if hasattr(name_or_node, 'node_type') and name_or_node.node_type == "ListAccess":
             list_value = self.eval_list_access(name_or_node)
@@ -1025,22 +840,11 @@ class Interpreter:
         return list_value[index]
     
 
-    # ========================================================================
-    # RETURN ('reclaim') - Uses exception unwinding so the return value
-    # bubbles up cleanly through any number of nested blocks/loops/ifs.
-    # eval_function_call catches ReturnValue and uses its .value as the
-    # call's result.
-    # ========================================================================
     def eval_return(self, node):
         value = self.interpret(node.children[0]) if node.children else None
         raise ReturnValue(value)
 
 
-    # ========================================================================
-    # FUNCTION CALL - Looks up the function, validates arg count, binds
-    # parameters into a fresh scope, and runs the body. ReturnValue is
-    # caught to extract 'reclaim'-returned values.
-    # ========================================================================
     def eval_function_call(self, node):
         function_name = node.value
         args = [self.interpret(arg.children[0]) for arg in node.children]
@@ -1066,7 +870,6 @@ class Interpreter:
                 param_type = param["type"]
                 arg_value = args[i]
                 is_list = param.get("is_list", False)
-                #print(f"\n[CALL] In function: {function_name} — Argument '{param_name}' of type '{param_type}' with value: {arg_value}")
                 self.declare_variable(param_name, param_type, arg_value, is_list=is_list)
 
             try:
@@ -1082,11 +885,6 @@ class Interpreter:
             self.current_func_name = None
 
 
-    # ========================================================================
-    # LIST OPERATIONS - append, insert, remove
-    # These mutate the underlying Python list stored in the variable's value.
-    # Index validation matches eval_list_access (0-based bounds).
-    # ========================================================================
     def eval_append(self, node):
         list_name = node.parent.children[0].value
         list_info = self.lookup_variable(list_name)
@@ -1094,7 +892,6 @@ class Interpreter:
         for child in node.children:
             value = self.interpret(child)
             list_info["value"].append(value)
-            #print(f"\nAppending value '{value}' to list '{list_name}'")
 
         
     def eval_insert(self, node):
@@ -1113,7 +910,6 @@ class Interpreter:
             value = self.interpret(child)
             list_info["value"].insert(index, value)
             index += 1
-            #print(f"Inserted {value} at index {index} in list '{list_name}': {list_info['value']}")
 
 
     def eval_remove(self, node):
@@ -1133,26 +929,16 @@ class Interpreter:
             raise InterpreterError(f"Runtime Error: Index {index} out of bounds for remove", node.line)
 
         removed = list_info["value"].pop(index)
-        #print(f"Removed value {removed} from list '{list_name}': {list_info['value']}")
-
-    # ========================================================================
-    # UNARY OPERATIONS - x++, x--, ~x (negate), !x (logical not)
-    # Increment/decrement mutate the variable in place; ~ and ! return a
-    # new value without mutation. Works on both simple variables and
-    # list elements (arr[i]++).
-    # ========================================================================
+
     def eval_unaryop(self, node):
-        # ++ / -- on a bundle member: ++p.age;  p.addr.zip--;
         if isinstance(node.children[0], MemberAccessNode) and node.value in {"++", "--"}:
             target = node.children[0]
-            # Walk the member chain to find the leaf bundle dict + final member name
             chain = []
             current = target
             while isinstance(current, MemberAccessNode):
                 chain.append(current.children[1].value)
                 current = current.children[0]
             chain.reverse()
-            # current is now an Object/Identifier node carrying the root variable name
             obj_name = current.value
             var_info = self.lookup_variable(obj_name)
             if isinstance(var_info, str):
@@ -1160,7 +946,6 @@ class Interpreter:
             bundle_value = var_info["value"]
             if not isinstance(bundle_value, dict):
                 raise InterpreterError(f"Runtime Error: Variable '{obj_name}' is not a bundle.", node.line)
-            # Navigate down to the parent dict (all but last member)
             for member in chain[:-1]:
                 if member not in bundle_value:
                     raise InterpreterError(f"Runtime Error: Bundle has no member '{member}'.", node.line)
@@ -1186,7 +971,7 @@ class Interpreter:
                 if node.position == "pre":
                     var_info["value"] += 1
                     return var_info["value"]
-                else:  # post
+                else:
                     original = var_info["value"]
                     var_info["value"] += 1
                     return original
@@ -1197,7 +982,7 @@ class Interpreter:
                 if node.position == "pre":
                     var_info["value"] -= 1
                     return var_info["value"]
-                else:  # post
+                else:
                     original = var_info["value"]
                     var_info["value"] -= 1
                     return original
@@ -1246,14 +1031,8 @@ class Interpreter:
                 return original if node.position == "post" else list_value[index]
 
         
-            
-
         raise InterpreterError(f"Unknown unary operator {node.value}", node.line)
     
-    # ========================================================================
-    # TYPE CAST - Converts a value to the named GAL type. Supports the five
-    # data types: seed, tree, leaf, branch, vine.
-    # ========================================================================
     def eval_cast(self, node):
         value = self.interpret(node.children[1])
         cast_type = node.children[0].value
@@ -1264,7 +1043,7 @@ class Interpreter:
             return float(value)
         elif cast_type == "leaf":
             if isinstance(value, int):
-                return chr(value)        # int -> ASCII character
+                return chr(value)
             return str(value)[0] if value else '\0'
         elif cast_type == "branch":
             return bool(value)
@@ -1274,21 +1053,12 @@ class Interpreter:
             raise InterpreterError(f"Unknown cast type: {cast_type}", node.line)
 
 
-    # ========================================================================
-    # STRING / LIST UTILITY HELPERS - taper, ts, soil, bloom
-    #   taper  : split a vine into a list of leaves (characters)
-    #   ts     : length of a list, vine, or leaf-array
-    #   soil   : lowercase a string
-    #   bloom  : uppercase a string
-    # These are GAL's built-in string/collection primitives.
-    # ========================================================================
     def eval_taper(self, node):
         var_name = node.children[0].value
         var_info = self.lookup_variable(var_name)
         
         if var_info["type"] == "leaf":
             value = list(var_info["value"])
-            #print(f"Tapered string '{var_name}' into list: {var_info['value']}")
 
         return value
 
@@ -1314,18 +1084,11 @@ class Interpreter:
         var_info = self.lookup_variable(var_name)
         return var_info["value"].upper()
 
-    # ========================================================================
-    # CONDITIONAL: spring / bud / wither (if / else-if / else)
-    # GAL chains: spring (cond) {} bud (cond) {} bud (cond) {} wither {}
-    # We evaluate the spring condition, then bud chain, then wither default.
-    # The condition must be a boolean (branch type).
-    # ========================================================================
     def eval_if_statement(self, node):
         condition_result = self.interpret(node.children[0].children[0])
         self.enter_scope()
 
 
-        
         try:
             if condition_result:
                 self.eval_block(node.children[1])
@@ -1345,14 +1108,12 @@ class Interpreter:
                         if elif_condition_result:
                             try:
                                 self.enter_scope()
-                                #print(f"Executing ElseIf block: {elif_node.line}")
                                 self.eval_block(elif_node.children[1])
                             finally:
                                 self.exit_scope()
                             return
                         
                     elif elif_node.node_type == "ElseStatement":
-                        #print(f"Executing Else block: {elif_node.line}")
                         try:
                             self.enter_scope()
                             self.eval_block(elif_node.children[0])
@@ -1366,16 +1127,10 @@ class Interpreter:
 
         return None
     
-    # ========================================================================
-    # LOOPS: cultivate (for), grow (while), tend (do-while)
-    # All three use the same MAX_LOOP_ITERATIONS guard (10000) to catch
-    # runaway loops during a demo. Each tracks break/continue flags so
-    # 'prune' exits the loop and 'skip' jumps to the next iteration.
-    # ========================================================================
     def eval_for_loop(self, node):
         self.enter_loop('for')
         self.enter_scope()
-        MAX_LOOP_ITERATIONS = 10000              # Runaway-loop safety net
+        MAX_LOOP_ITERATIONS = 10000
         LOOP_COUNTER = 0
 
         try:
@@ -1487,12 +1242,6 @@ class Interpreter:
             self.exit_loop()
 
     
-    # ========================================================================
-    # BREAK / CONTINUE - 'prune' and 'skip'
-    # These set flags that the surrounding block / loop checks each
-    # iteration. The loop_stack ensures break/continue can only be used
-    # inside a loop or switch.
-    # ========================================================================
     def eval_break(self, node):
         if self.loop_stack:
             self.trigger_break()
@@ -1506,7 +1255,6 @@ class Interpreter:
         return self.break_flag
 
     def enter_loop(self, loop_type):
-        # Push a new loop frame; reset break/continue so they don't carry over
         self.loop_stack.append(loop_type)
         self.break_flag = False
         self.continue_flag = False
@@ -1530,11 +1278,6 @@ class Interpreter:
         self.continue_flag = True
 
 
-    # ========================================================================
-    # SWITCH: harvest / variety / soil  (switch / case / default)
-    # Cases match the switch value. 'prune' inside a case exits the switch.
-    # 'soil' is the default case (executes if no variety matched).
-    # ========================================================================
     def eval_switch(self, node):
         self.enter_loop('switch')
         self.enter_scope()
@@ -1579,44 +1322,28 @@ class Interpreter:
             self.exit_scope()
 
 
-    # ========================================================================
-    # INPUT SYSTEM ('water')
-    # When water() runs, the interpreter:
-    #   1. emit_input_request   -> tells the client to show an input box
-    #   2. wait_for_input        -> parks on an Event (eventlet or threading)
-    #   3. (client emits 'capture_input' -> server calls provide_input)
-    #   4. provide_input         -> .send() / .set() unblocks the waiter
-    #   5. wait_for_input returns the typed string
-    #   6. eval_input parses and type-checks it (e.g. ~5 -> -5 for seed)
-    # ========================================================================
     def emit_input_request(self, var_name, prompt):
-        # Tell the client a water() prompt is needed
         self.socketio.emit('input_required', {'prompt': prompt, 'variable': var_name})
 
-    # Method to capture input from the client
     def provide_input(self, var_name, input_value):
         evt = self.input_events.get(var_name)
         if evt is None:
-            # No waiter yet — stash the value for later
             self.input_values[var_name] = input_value
             return
         if _USE_EVENTLET:
-            # eventlet.event.Event.send() unblocks the waiting greenlet
             evt.send(input_value)
         else:
             self.input_values[var_name] = input_value
             evt.set()
 
-    # Method to wait for input asynchronously
     def wait_for_input(self, var_name):
-        # Check if input was already stashed (provide_input called first)
         if var_name in self.input_values:
             return self.input_values.pop(var_name)
 
         if _USE_EVENTLET:
             evt = _ev.Event()
             self.input_events[var_name] = evt
-            value = evt.wait()          # cooperative yield
+            value = evt.wait()
             self.input_events.pop(var_name, None)
             if getattr(self, '_cancelled', False):
                 raise _CancelledError()
@@ -1631,14 +1358,6 @@ class Interpreter:
             self.input_events.pop(var_name, None)
             return value
 
-    # ========================================================================
-    # EVAL_INPUT - Implements 'water(...)'. Determines what type of value
-    # the receiving variable expects, prompts the user, then validates and
-    # converts the typed input to that type. Enforces strict GAL syntax:
-    #   - Negative numbers must use '~' (not '-')
-    #   - Booleans must be 'sunshine' or 'frost' (not 'true'/'false')
-    # Errors include a "did you mean" suggestion to guide the user.
-    # ========================================================================
     def eval_input(self, node):
         parent_node = node.parent
         if isinstance(parent_node, VariableDeclarationNode):
@@ -1648,8 +1367,6 @@ class Interpreter:
         elif isinstance(parent_node, AssignmentNode):
             target = parent_node.children[0]
             if isinstance(target, ListAccessNode):
-                # water(arr[i]) — target is a list access node
-                # Walk down to find the base list name
                 current = target
                 while hasattr(current, 'node_type') and current.node_type == "ListAccess":
                     current = current.children[0].value
@@ -1660,7 +1377,6 @@ class Interpreter:
                 var_type = self.lookup_variable(var_name)["type"]
 
         else:
-            # Standalone water() / water(type) — extract type from node value
             var_name = "_input"
             if node.value and "(" in node.value:
                 inner = node.value.split("(")[1].rstrip(")")
@@ -1668,21 +1384,18 @@ class Interpreter:
             else:
                 var_type = "vine"
 
-        prompt = f"Input for {var_name}: "  # Create a prompt message for the input
+        prompt = f"Input for {var_name}: "
         self.input_required = True
 
 
-        # Emit the input request to the client
         self.emit_input_request(var_name, prompt)
 
-        # Wait for the input asynchronously
         input_value = self.wait_for_input(var_name)
 
 
-        self.input_required = False  # Reset the input flag
+        self.input_required = False
 
         if var_type == "seed":
-            # GAL uses ~ for negative numbers; '-' is NOT accepted at input
             original_input = input_value
             if isinstance(input_value, str) and input_value.startswith('-'):
                 raise InterpreterError(f"Runtime Error: GAL uses '~' for negative numbers, not '-'. Got '{original_input}'; did you mean '~{original_input[1:]}'?", node.line)
@@ -1696,7 +1409,6 @@ class Interpreter:
                 raise InterpreterError(f"Runtime Error: Expected integer value, got '{original_input}'", node.line)
 
         elif var_type == "tree":
-            # GAL uses ~ for negative numbers; '-' is NOT accepted at input
             original_input = input_value
             if isinstance(input_value, str) and input_value.startswith('-'):
                 raise InterpreterError(f"Runtime Error: GAL uses '~' for negative numbers, not '-'. Got '{original_input}'; did you mean '~{original_input[1:]}'?", node.line)
@@ -1721,7 +1433,6 @@ class Interpreter:
                 raise InterpreterError(f"Runtime Error: Expected float value, got '{original_input}'", node.line)
 
         elif var_type == "branch":
-            # GAL booleans are 'sunshine' (true) and 'frost' (false); 'true'/'false' are NOT accepted
             if input_value == "true" or input_value == "false":
                 suggestion = "sunshine" if input_value == "true" else "frost"
                 raise InterpreterError(f"Runtime Error: GAL uses 'sunshine' and 'frost' for booleans, not 'true'/'false'. Got '{input_value}'; did you mean '{suggestion}'?", node.line)

Backend/lexer/__init__.py

@@ -1,16 +1,6 @@
-# ============================================================================
-# LEXER PACKAGE - Public API for the lexical-analysis phase
-# ============================================================================
-# Re-exports everything needed by external callers (server.py, parser, tests).
-# After the modular restructure, `from lexer import lex, Token, TT_RW_ROOT, ...`
-# still works exactly as before — the Lexer class itself lives in
-# lexer/scanner.py, while shared types live in tokens.py / positions.py /
-# errors.py at the Backend/ root.
-# ============================================================================
 
-from .scanner import Lexer, lex                           # the FSM + main entry point
+from .scanner import Lexer, lex
 
-# Re-export shared types so old `from lexer import X` callers keep working.
 from shared.tokens import *  # noqa: F401,F403  - TT_* constants
 from shared.tokens import Token, get_token_description  # noqa: F401  - explicit
 from lexer.positions import Position  # noqa: F401

Backend/lexer/delimiters.py

@@ -1,54 +1,43 @@
-# ============================================================================
-# DELIMITER SETS - Character sets used by the lexer's FSM
-# ============================================================================
-# Each delim* set names the characters that may legally appear AFTER a
-# specific token type. The lexer consults these to enforce GAL's strict
-# delimiter rules and reject ambiguous trailing characters.
-# ============================================================================
 
-# --- CHARACTER CLASSES ---
-ZERO = '0'                                          # Zero digit (special case for leading zeros)
-DIGIT = '123456789'                                 # Non-zero digits
-ZERODIGIT = ZERO + DIGIT                            # All digits (0-9)
+ZERO = '0'
+DIGIT = '123456789'
+ZERODIGIT = ZERO + DIGIT
 
-LOW_ALPHA = 'abcdefghijklmnopqrstuvwxyz'            # Lowercase letters
-UPPER_ALPHA = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'          # Uppercase letters
-ALPHA = LOW_ALPHA + UPPER_ALPHA                     # All letters
-ALPHANUM = ALPHA + ZERODIGIT + '_'                  # Identifier characters
+LOW_ALPHA = 'abcdefghijklmnopqrstuvwxyz'
+UPPER_ALPHA = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
+ALPHA = LOW_ALPHA + UPPER_ALPHA
+ALPHANUM = ALPHA + ZERODIGIT + '_'
 
-# --- DELIMITER SETS ---
-# Delimiters are characters that can legally appear AFTER certain tokens.
-# Different token types have different valid delimiters to ensure proper syntax.
 space_delim = {' ', '\t', '\n'}                                                    
-delim2 = {':'}                                                                             # after 'soil' (default case)
-delim3 = {'{'}                                                                                  # after 'tend', 'wither'
-delim4 = {':', '('}                                                                             # after 'bud', 'cultivate', 'harvest'
-delim5 = {'('}                                                                                  # after keywords requiring (
-delim6 = {';', ',', '=', '>', '<', '!', '}', ')', '('}                                          # after 'spring', 'plant', 'water'
-delim7 = {'('}                                                                                  # after 'root'
-delim8 = {';'}                                                                                  # after statements needing ;
-delim9 = set(ALPHA + '(' + ',' + ';' + ')')                                                     # function-related contexts
-delim10 = {';', ')'}                                                                            # closing statements
-delim11 = set([LOW_ALPHA, ZERODIGIT, ']', '~'])                                                      # newline-only
-delim12 = set(ALPHA + ZERODIGIT + ']' + '~')                                                    # array/negation contexts
-delim13 = {';', ')', '['}                                                                       # mixed statement endings
-delim14 = set(ALPHA + ZERODIGIT + '"' + "'" + '{')                                              # before literals/blocks
-delim15 = {'\n', ';', '}', ','}                                                                 # multi-context endings
-delim16 = set(ALPHANUM + ')' + '"' + '!' + '(' + '[' + '\'')                                    # expression contexts
-delim17 = {'}', ';', ',', '+', '-', '*', '/', '%', '=', '>', '<', '!', '&', '|'}                # operator contexts
-delim18 = {';', '{', ')', '&', '|', '+', '-', '*', '/', '%'}                                    # logical/arithmetic contexts
-delim19 = {';', ',', '}', ')', '=', '>', '<', '!'}                                              # comparison contexts
-delim20 = set(ALPHA + ZERODIGIT + '"' + "'" + '{')                                              # before string/char literals
-delim21 = set(DIGIT)                                                                            # digit delimiters
-delim22 = {',', ';', '(', ')', '{', '[', ']'}                                                   # punctuation contexts
-delim23 = {';', ',', '}', ']', ')', ':', '+', '-', '*', '/', '%', '=', '>', '<', '!', '&', '|'} # after literals
-delim24 = set(ZERODIGIT + ALPHA + '~!(' + "\"'" + ' \t\n')                                     # expression starts after + or +=
-delim25 = set(ALPHANUM + ';}) \t\n')                                                             # after prefix/postfix ++ or --
-delim26 = {'(', '['} | set(ALPHA) | {' ', '\t', '\n'}                                            # { (, alphabet, [, whitespace }
+delim2 = {':'}
+delim3 = {'{'}
+delim4 = {':', '('}
+delim5 = {'('}
+delim6 = {';', ',', '=', '>', '<', '!', '}', ')', '('}
+delim7 = {'('}
+delim8 = {';'}
+delim9 = set(ALPHA + '(' + ',' + ';' + ')')
+delim10 = {';', ')'}
+delim11 = set([LOW_ALPHA, ZERODIGIT, ']', '~'])
+delim12 = set(ALPHA + ZERODIGIT + ']' + '~')
+delim13 = {';', ')', '['}
+delim14 = set(ALPHA + ZERODIGIT + '"' + "'" + '{')
+delim15 = {'\n', ';', '}', ','}
+delim16 = set(ALPHANUM + ')' + '"' + '!' + '(' + '[' + '\'')
+delim17 = {'}', ';', ',', '+', '-', '*', '/', '%', '=', '>', '<', '!', '&', '|'}
+delim18 = {';', '{', ')', '&', '|', '+', '-', '*', '/', '%'}
+delim19 = {';', ',', '}', ')', '=', '>', '<', '!'}
+delim20 = set(ALPHA + ZERODIGIT + '"' + "'" + '{')
+delim21 = set(DIGIT)
+delim22 = {',', ';', '(', ')', '{', '[', ']'}
+delim23 = {';', ',', '}', ']', ')', ':', '+', '-', '*', '/', '%', '=', '>', '<', '!', '&', '|'}
+delim24 = set(ZERODIGIT + ALPHA + '~!(' + "\"'" + ' \t\n')
+delim25 = set(ALPHANUM + ';}) \t\n')
+delim26 = {'(', '['} | set(ALPHA) | {' ', '\t', '\n'}
 idf_delim = {' ', ',', ';', '(', ')', '{', '}', '[', ']', ':', '+', '-', '*', '/', '%',
-             '>', '<', '=', '\t', '\n', '.', '"', "'"}                                          # after identifiers
+             '>', '<', '=', '\t', '\n', '.', '"', "'"}
 whlnum_delim = {';', ' ', ',', '}', ']', ')', ':', '+', '-', '*', '/', '%', '=', '>', '<',
-                '!', '&', '|', '\t', '\n'}                                                      # after integers
+                '!', '&', '|', '\t', '\n'}
 decim_delim = {'}', ';', ',', '+', '-', '*', '/', '%', '=', '>', '<', '!', '&', '|', ' ',
-               '\t', '\n', ')', ']'}                                                            # after floats/doubles
-comment_delim = set(ALPHANUM + ';+-*/%}{()' + '\n')                                             # within comments
+               '\t', '\n', ')', ']'}
+comment_delim = set(ALPHANUM + ';+-*/%}{()' + '\n')

Backend/lexer/errors.py

@@ -1,19 +1,11 @@
-# ============================================================================
-# LEXICAL ERROR - Raised by the lexer FSM on illegal characters / delimiters
-# ============================================================================
-# Stores a Position so the IDE can highlight the offending column.
-# Lives next to the scanner because lexical errors are a pure lexer concern.
-# ============================================================================
 
 
 class LexicalError:
-    """Stores information about a lexical error (position and description)"""
 
     def __init__(self, pos, details):
-        self.pos = pos          # Position object where error occurred
-        self.details = details  # Error description
+        self.pos = pos
+        self.details = details
 
     def as_string(self):
-        """Returns the error message in readable string format"""
-        self.details = self.details.replace('\n', '\\n')  # Escape newlines in error message
+        self.details = self.details.replace('\n', '\\n')
         return f"LEXICAL error line {self.pos.ln} col {self.pos.col} {self.details}"

Backend/lexer/positions.py

@@ -1,31 +1,21 @@
-# ============================================================================
-# POSITION CLASS - Tracks current location in source code
-# ============================================================================
-# Extracted from lexer.py during the modular restructure.
-# Shared by every compiler phase that needs to report source locations
-# (lexer, parser, semantic analyzer, ICG, interpreter).
-# ============================================================================
 
 
 class Position:
-    """Tracks the position (line, column, index) in the source code for error reporting"""
 
     def __init__(self, index, ln, col=0):
-        self.index = index  # Character index in source code (0-based)
-        self.ln = ln        # Line number (1-based)
-        self.col = col      # Column number (0-based)
+        self.index = index
+        self.ln = ln
+        self.col = col
 
     def advance(self, current_char):
-        """Advance to the next character, updating line/column numbers"""
         self.index += 1
         self.col += 1
 
-        if current_char == '\n':  # New line detected
+        if current_char == '\n':
             self.ln += 1
-            self.col = 0  # Reset column to start of line
+            self.col = 0
 
         return self
 
     def copy(self):
-        """Returns a copy of the current position (for error tracking)"""
         return Position(self.index, self.ln, self.col)

Backend/lexer/scanner.py

@@ -1,12 +1,3 @@
-# ============================================================================
-# LEXER SCANNER - The Lexer FSM and the lex() entry point
-# ============================================================================
-# Extracted from the monolithic Backend/lexer.py during the modular restructure.
-# This file contains the Lexer class (character-by-character FSM) plus the
-# lex() helper that wraps it. Shared types (Token, Position, LexicalError,
-# TT_* constants) live in tokens.py / positions.py / errors.py and are
-# imported below. Character / delimiter sets live in delimiters.py.
-# ============================================================================
 from shared.tokens import *  # noqa: F401,F403  - TT_* constants used heavily by the FSM
 from shared.tokens import Token, get_token_description  # noqa: F401  - explicit re-export
 from lexer.positions import Position
@@ -22,177 +13,147 @@ from lexer.delimiters import (
 
 
 class Lexer:
-    """
-    The Lexer class performs lexical analysis on GAL source code.
-    It scans character by character and groups them into tokens.
-    """
     def __init__(self, source_code): 
-        self.source_code = source_code.replace('\r', '')  # Strip carriage returns (Windows \r\n → \n)
-        self.pos = Position(-1, 1, -1)     # Current position (starts before first char)
-        self.current_char = None           # Current character being examined
-        self.advance()                     # Move to first character
+        self.source_code = source_code.replace('\r', '')
+        self.pos = Position(-1, 1, -1)
+        self.current_char = None
+        self.advance()
 
     def advance(self):
-        """Advance to the next character in the source code"""
         self.pos.advance(self.current_char)
-        # Get character at current index, or None if at end
         self.current_char = self.source_code[self.pos.index] if self.pos.index<len(self.source_code) else None
 
     def make_tokens(self):
-        """
-        Main tokenization method - converts source code into tokens.
-        Returns: (tokens, errors) tuple
-        - tokens: list of Token objects
-        - errors: list of LexicalError objects
-        """
-        tokens = []                                                  # accumulator: every recognized Token is appended here
-        line = 1                                                     # running line number (1-indexed for user-facing errors)
-        errors = []                                                  # accumulator: every LexicalError encountered is appended here
-        pos = self.pos.copy()                                        # snapshot of current pos; reused as fallback for EOF token at end
+        tokens = []
+        line = 1
+        errors = []
+        pos = self.pos.copy()
 
-        # Main loop: drive the FSM one character at a time until source is exhausted (current_char becomes None).
-        while self.current_char != None:                             # None sentinel = end of source_code reached
+        while self.current_char != None:
 
-            # =====================================================================
-            # KEYWORD & IDENTIFIER RECOGNITION
-            # Hand-written transition diagram: each branch matches one keyword.
-            # If no keyword path completes, the trailing "else" falls through to
-            # generic identifier scanning at the bottom of this if-block.
-            # =====================================================================
-            if self.current_char in ALPHA:                           # only letters can start a keyword/identifier (digits cannot)
-                ident_str = ''                                       # buffer that will hold the lexeme as we walk it character-by-character
-                pos = self.pos.copy()                                # capture starting position so error/Token carries the *first* char's line/col
+            if self.current_char in ALPHA:
+                ident_str = ''
+                pos = self.pos.copy()
 
-                # --- Letter B: 'branch', 'bud', 'bundle' ---
-                if self.current_char == "b":                         # FSM root for words starting with 'b'
-                    ident_str += self.current_char                   # buffer the 'b'
-                    self.advance()                                   # consume it; current_char now points to the 2nd letter
-                    if self.current_char == "r":                     # 'b'+'r' → potentially "branch"
-                        ident_str += self.current_char               # buffer the 'r'
-                        self.advance()                               # consume 'r'; look at 3rd letter
-                        if self.current_char == "a":                 # 'br'+'a' → still on track for "branch"
-                            ident_str += self.current_char           # buffer the 'a'
-                            self.advance()                           # consume 'a'
-                            if self.current_char == "n":             # 'bra'+'n'
-                                ident_str += self.current_char       # buffer the 'n'
-                                self.advance()                       # consume 'n'
-                                if self.current_char == "c":         # 'bran'+'c'
-                                    ident_str += self.current_char   # buffer the 'c'
-                                    self.advance()                   # consume 'c'
-                                    if self.current_char == "h":     # 'branc'+'h' → full keyword spelled out
-                                        ident_str += self.current_char  # buffer the trailing 'h'
-                                        self.advance()               # consume 'h'; current_char is now whatever comes AFTER "branch"
-                                        # Maximal-munch check: only emit BRANCH token if the next char is a legal delimiter.
-                                        # Otherwise "branchx" must become an identifier, not keyword+identifier.
+                if self.current_char == "b":
+                    ident_str += self.current_char
+                    self.advance()
+                    if self.current_char == "r":
+                        ident_str += self.current_char
+                        self.advance()
+                        if self.current_char == "a":
+                            ident_str += self.current_char
+                            self.advance()
+                            if self.current_char == "n":
+                                ident_str += self.current_char
+                                self.advance()
+                                if self.current_char == "c":
+                                    ident_str += self.current_char
+                                    self.advance()
+                                    if self.current_char == "h":
+                                        ident_str += self.current_char
+                                        self.advance()
                                         if self.current_char is None or self.current_char in space_delim or self.current_char == ';':
-                                            tokens.append(Token(TT_RW_BRANCH, ident_str, line, pos.col))  # emit reserved-word token
-                                            continue                 # restart the outer while loop — do NOT fall through to identifier scan
-                                        elif self.current_char not in ALPHANUM:  # any non-alphanumeric (e.g. '(', '{') also closes the keyword
-                                            tokens.append(Token(TT_RW_BRANCH, ident_str, line, pos.col))  # emit reserved-word token
-                                            continue                 # restart the outer while loop
-                    elif self.current_char == "u":                       # 'b'+'u' → either "bud" or "bundle"
-                        ident_str += self.current_char                   # buffer the 'u'
-                        self.advance()                                   # consume 'u'
-                        if self.current_char == "d":                     # 'bu'+'d' → potentially "bud"
-                            ident_str += self.current_char               # buffer the 'd'
-                            self.advance()                               # consume 'd'; check what follows
-                            # Maximal-munch: "bud" needs whitespace or delim4 ({':', '('}) to terminate.
+                                            tokens.append(Token(TT_RW_BRANCH, ident_str, line, pos.col))
+                                            continue
+                                        elif self.current_char not in ALPHANUM:
+                                            tokens.append(Token(TT_RW_BRANCH, ident_str, line, pos.col))
+                                            continue
+                    elif self.current_char == "u":
+                        ident_str += self.current_char
+                        self.advance()
+                        if self.current_char == "d":
+                            ident_str += self.current_char
+                            self.advance()
                             if self.current_char is None or (self.current_char is not None and self.current_char.isspace()) or self.current_char in delim4:
-                                tokens.append(Token(TT_RW_BUD, ident_str, line, pos.col))  # emit BUD reserved-word token
-                                continue                                 # restart outer loop on next char
+                                tokens.append(Token(TT_RW_BUD, ident_str, line, pos.col))
+                                continue
                             elif self.current_char is not None and not self.current_char.isspace() and self.current_char not in delim4 and self.current_char not in ALPHANUM:
-                                # Strict rule: an illegal delimiter after the keyword is a lexical error (not a fallback to identifier).
                                 errors.append(LexicalError(pos, f"Invalid delimiter '{self.current_char}' after '{ident_str}'"))
-                                self.advance()                           # skip the bad char so we don't loop forever
-                                continue                                 # back to outer scan
-                        elif self.current_char == "n":                   # 'bu'+'n' → potentially "bundle"
-                            ident_str += self.current_char               # buffer 'n'
-                            self.advance()                               # consume 'n'
-                            if self.current_char == "d":                 # 'bun'+'d'
-                                ident_str += self.current_char           # buffer 'd'
-                                self.advance()                           # consume 'd'
-                                if self.current_char == "l":             # 'bund'+'l'
-                                    ident_str += self.current_char       # buffer 'l'
-                                    self.advance()                       # consume 'l'
-                                    if self.current_char == "e":         # 'bundl'+'e' → "bundle" complete
-                                        ident_str += self.current_char   # buffer trailing 'e'
-                                        self.advance()                   # consume 'e'
-                                        if self.current_char is not None and self.current_char in space_delim:  # bundle requires whitespace next
-                                            tokens.append(Token(TT_RW_BUNDLE, ident_str, line, pos.col))  # emit BUNDLE token
-                                            continue                     # next iteration
+                                self.advance()
+                                continue
+                        elif self.current_char == "n":
+                            ident_str += self.current_char
+                            self.advance()
+                            if self.current_char == "d":
+                                ident_str += self.current_char
+                                self.advance()
+                                if self.current_char == "l":
+                                    ident_str += self.current_char
+                                    self.advance()
+                                    if self.current_char == "e":
+                                        ident_str += self.current_char
+                                        self.advance()
+                                        if self.current_char is not None and self.current_char in space_delim:
+                                            tokens.append(Token(TT_RW_BUNDLE, ident_str, line, pos.col))
+                                            continue
                                         elif self.current_char is not None and self.current_char not in space_delim and self.current_char not in ALPHANUM:
-                                            # Anything else (and not a letter that would extend it to an identifier) → illegal delimiter error.
                                             errors.append(LexicalError(pos, f"Invalid delimiter '{self.current_char}' after '{ident_str}'"))
-                                            self.advance()               # skip bad char
-                                            continue                     # restart outer scan
+                                            self.advance()
+                                            continue
 
-                #Letter C
-                elif self.current_char == "c":                           # FSM root for words starting with 'c' (only "cultivate")
-                    ident_str += self.current_char                       # buffer 'c'
-                    self.advance()                                       # consume 'c'
-                    if self.current_char == "u":                         # 'c'+'u' → on track for "cultivate"
-                        ident_str += self.current_char                   # buffer 'u'
-                        self.advance()                                   # consume 'u'
-                        if self.current_char == "l":                     # 'cu'+'l'
-                            ident_str += self.current_char               # buffer 'l'
-                            self.advance()                               # consume 'l'
-                            if self.current_char == "t":                 # 'cul'+'t'
-                                ident_str += self.current_char           # buffer 't'
-                                self.advance()                           # consume 't'
-                                if self.current_char == "i":             # 'cult'+'i'
-                                    ident_str += self.current_char       # buffer 'i'
-                                    self.advance()                       # consume 'i'
-                                    if self.current_char == "v":         # 'culti'+'v'
-                                        ident_str += self.current_char   # buffer 'v'
-                                        self.advance()                   # consume 'v'
-                                        if self.current_char == "a":     # 'cultiv'+'a'
-                                            ident_str += self.current_char  # buffer 'a'
-                                            self.advance()               # consume 'a'
-                                            if self.current_char == "t": # 'cultiva'+'t'
-                                                ident_str += self.current_char  # buffer 't'
-                                                self.advance()           # consume 't'
-                                                if self.current_char == "e":  # 'cultivat'+'e' → "cultivate" complete
-                                                    ident_str += self.current_char  # buffer trailing 'e'
-                                                    self.advance()       # consume 'e'
-                                                    # cultivate (for-loop) requires whitespace or delim4 ({':', '('}) next.
+                elif self.current_char == "c":
+                    ident_str += self.current_char
+                    self.advance()
+                    if self.current_char == "u":
+                        ident_str += self.current_char
+                        self.advance()
+                        if self.current_char == "l":
+                            ident_str += self.current_char
+                            self.advance()
+                            if self.current_char == "t":
+                                ident_str += self.current_char
+                                self.advance()
+                                if self.current_char == "i":
+                                    ident_str += self.current_char
+                                    self.advance()
+                                    if self.current_char == "v":
+                                        ident_str += self.current_char
+                                        self.advance()
+                                        if self.current_char == "a":
+                                            ident_str += self.current_char
+                                            self.advance()
+                                            if self.current_char == "t":
+                                                ident_str += self.current_char
+                                                self.advance()
+                                                if self.current_char == "e":
+                                                    ident_str += self.current_char
+                                                    self.advance()
                                                     if self.current_char is None or (self.current_char is not None and self.current_char.isspace()) or self.current_char in delim4:
-                                                        tokens.append(Token(TT_RW_CULTIVATE, ident_str, line, pos.col))  # emit CULTIVATE token
-                                                        continue         # next iteration
+                                                        tokens.append(Token(TT_RW_CULTIVATE, ident_str, line, pos.col))
+                                                        continue
                                                     elif self.current_char is not None and not self.current_char.isspace() and self.current_char not in delim4 and self.current_char not in ALPHANUM:
-                                                        errors.append(LexicalError(pos, f"Invalid delimiter '{self.current_char}' after '{ident_str}'"))  # illegal trailer
-                                                        self.advance()   # skip bad char
-                                                        continue         # restart outer scan
+                                                        errors.append(LexicalError(pos, f"Invalid delimiter '{self.current_char}' after '{ident_str}'"))
+                                                        self.advance()
+                                                        continue
 
-                # Letter E
-                elif self.current_char == "e":                           # FSM root for 'e' (only "empty")
-                    ident_str += self.current_char                       # buffer 'e'
-                    self.advance()                                       # consume 'e'
-                    if self.current_char == "m":                         # 'e'+'m' → potentially "empty"
-                        ident_str += self.current_char                   # buffer 'm'
-                        self.advance()                                   # consume 'm'
-                        if self.current_char == "p":                     # 'em'+'p'
-                            ident_str += self.current_char               # buffer 'p'
-                            self.advance()                               # consume 'p'
-                            if self.current_char == "t":                 # 'emp'+'t'
-                                ident_str += self.current_char           # buffer 't'
-                                self.advance()                           # consume 't'
-                                if self.current_char == "y":             # 'empt'+'y' → "empty" complete
-                                    ident_str += self.current_char       # buffer trailing 'y'
-                                    self.advance()                       # consume 'y'
-                                    # empty is the void return type; whitespace is a valid delimiter.
+                elif self.current_char == "e":
+                    ident_str += self.current_char
+                    self.advance()
+                    if self.current_char == "m":
+                        ident_str += self.current_char
+                        self.advance()
+                        if self.current_char == "p":
+                            ident_str += self.current_char
+                            self.advance()
+                            if self.current_char == "t":
+                                ident_str += self.current_char
+                                self.advance()
+                                if self.current_char == "y":
+                                    ident_str += self.current_char
+                                    self.advance()
                                     if self.current_char is None or (self.current_char is not None and self.current_char.isspace()) or self.current_char in space_delim:
-                                        tokens.append(Token(TT_RW_EMPTY, ident_str, line, pos.col))  # emit EMPTY token
-                                        continue                         # next iteration
+                                        tokens.append(Token(TT_RW_EMPTY, ident_str, line, pos.col))
+                                        continue
                                     elif self.current_char is not None and not self.current_char.isspace() and self.current_char not in space_delim and self.current_char not in ALPHANUM:
-                                        errors.append(LexicalError(pos, f"Invalid delimiter '{self.current_char}' after '{ident_str}'"))  # illegal trailer
-                                        self.advance()                   # skip bad char
-                                        continue                         # restart outer scan
+                                        errors.append(LexicalError(pos, f"Invalid delimiter '{self.current_char}' after '{ident_str}'"))
+                                        self.advance()
+                                        continue
 
-                # Letter F
                 elif self.current_char == "f":
                     ident_str += self.current_char
                     self.advance()
-                    if self.current_char == "r": # frost
+                    if self.current_char == "r":
                         ident_str += self.current_char
                         self.advance()
                         if self.current_char == "o":
@@ -205,10 +166,9 @@ class Lexer:
                                     ident_str += self.current_char
                                     self.advance()
                                     if self.current_char is None or (self.current_char not in ALPHANUM and self.current_char != '_'):
-                                        tokens.append(Token(TT_BOOLLIT_FALSE, ident_str, line, pos.col)) # Boolean Literal
+                                        tokens.append(Token(TT_BOOLLIT_FALSE, ident_str, line, pos.col))
                                         continue
-                                    # If followed by alphanum/underscore, continue to identifier parsing
-                    elif self.current_char == "e": # fertile
+                    elif self.current_char == "e":
                         ident_str += self.current_char
                         self.advance()
                         if self.current_char == "r":
@@ -234,11 +194,10 @@ class Lexer:
                                                 self.advance()
                                                 continue
                                             
-                # Letter G
                 elif self.current_char == "g":
                     ident_str += self.current_char
                     self.advance()
-                    if self.current_char == "r": # grow
+                    if self.current_char == "r":
                         ident_str += self.current_char
                         self.advance()
                         if self.current_char == "o":
@@ -255,11 +214,10 @@ class Lexer:
                                     self.advance()
                                     continue
                                 
-                # Letter H
                 elif self.current_char == "h":
                     ident_str += self.current_char
                     self.advance()
-                    if self.current_char == "a": # harvest
+                    if self.current_char == "a":
                         ident_str += self.current_char
                         self.advance()
                         if self.current_char == "r":
@@ -285,11 +243,10 @@ class Lexer:
                                                 self.advance()
                                                 continue
                                 
-                # Letter L
                 elif self.current_char == "l":
                     ident_str += self.current_char
                     self.advance()
-                    if self.current_char == "e": # leaf
+                    if self.current_char == "e":
                         ident_str += self.current_char
                         self.advance()
                         if self.current_char == "a":
@@ -298,7 +255,6 @@ class Lexer:
                             if self.current_char == "f":
                                 ident_str += self.current_char
                                 self.advance()
-                                # Leaf keyword recognized - emit token
                                 if self.current_char is None or self.current_char in space_delim or self.current_char == ';':
                                     tokens.append(Token(TT_RW_LEAF, ident_str, line, pos.col))
                                     continue
@@ -306,11 +262,10 @@ class Lexer:
                                     tokens.append(Token(TT_RW_LEAF, ident_str, line, pos.col))
                                     continue
                         
-                # Letter P
                 elif self.current_char == "p":
                     ident_str += self.current_char
                     self.advance()
-                    if self.current_char == "l": # plant
+                    if self.current_char == "l":
                         ident_str += self.current_char
                         self.advance()
                         if self.current_char == "a":
@@ -329,7 +284,7 @@ class Lexer:
                                         errors.append(LexicalError(pos, f"Invalid delimiter '{self.current_char}' after '{ident_str}'"))
                                         self.advance()
                                         continue
-                    elif self.current_char == "o": # pollinate
+                    elif self.current_char == "o":
                         ident_str += self.current_char
                         self.advance()
                         if self.current_char == "l":
@@ -360,7 +315,7 @@ class Lexer:
                                                         errors.append(LexicalError(pos, f"Invalid delimiter '{self.current_char}' after '{ident_str}'"))
                                                         self.advance()
                                                         continue
-                    elif self.current_char == "r": # prune
+                    elif self.current_char == "r":
                         ident_str += self.current_char
                         self.advance()
                         if self.current_char == "u":
@@ -380,11 +335,10 @@ class Lexer:
                                         self.advance()
                                         continue
 
-                # Letter R
                 elif self.current_char == "r":
                     ident_str += self.current_char
                     self.advance()
-                    if self.current_char == "e": # reclaim
+                    if self.current_char == "e":
                         ident_str += self.current_char
                         self.advance()
                         if self.current_char == "c":
@@ -409,7 +363,7 @@ class Lexer:
                                                 errors.append(LexicalError(pos, f"Invalid delimiter '{self.current_char}' after '{ident_str}'"))
                                                 self.advance()
                                                 continue
-                    elif self.current_char == "o": # root
+                    elif self.current_char == "o":
                         ident_str += self.current_char
                         self.advance()
                         if self.current_char == "o":
@@ -423,14 +377,13 @@ class Lexer:
                                     continue
                                 elif self.current_char is not None and not self.current_char.isspace() and self.current_char not in delim7 and self.current_char not in ALPHANUM:
                                     errors.append(LexicalError(pos, f"Invalid delimiter '{self.current_char}' after '{ident_str}'"))
-                                    self.advance()  # Skip the invalid character
+                                    self.advance()
                                     continue
 
-                # Letter S
                 elif self.current_char == "s": 
                     ident_str += self.current_char
                     self.advance()
-                    if self.current_char == "e": # seed
+                    if self.current_char == "e":
                         ident_str += self.current_char
                         self.advance()
                         if self.current_char == "e":
@@ -439,14 +392,13 @@ class Lexer:
                             if self.current_char == "d":
                                 ident_str += self.current_char
                                 self.advance()
-                                # Seed keyword recognized - emit token
                                 if self.current_char is None or self.current_char in space_delim or self.current_char == ';':
                                     tokens.append(Token(TT_RW_SEED, ident_str, line, pos.col))
                                     continue
                                 elif self.current_char not in ALPHANUM:
                                     tokens.append(Token(TT_RW_SEED, ident_str, line, pos.col))
                                     continue
-                    elif self.current_char == "k": # skip
+                    elif self.current_char == "k":
                         ident_str += self.current_char
                         self.advance()
                         if self.current_char == "i":
@@ -462,7 +414,7 @@ class Lexer:
                                     errors.append(LexicalError(pos, f"Invalid delimiter '{self.current_char}' after '{ident_str}'"))
                                     self.advance()
                                     continue
-                    elif self.current_char == "o": # soil
+                    elif self.current_char == "o":
                         ident_str += self.current_char
                         self.advance()
                         if self.current_char == "i":
@@ -478,7 +430,7 @@ class Lexer:
                                     errors.append(LexicalError(pos, f"Invalid delimiter '{self.current_char}' after '{ident_str}'"))
                                     self.advance()
                                     continue
-                    elif self.current_char == "p": # spring
+                    elif self.current_char == "p":
                         ident_str += self.current_char
                         self.advance()
                         if self.current_char == "r":
@@ -500,7 +452,7 @@ class Lexer:
                                             errors.append(LexicalError(pos, f"Invalid delimiter '{self.current_char}' after '{ident_str}'"))
                                             self.advance()
                                             continue
-                    elif self.current_char == "u": # sunshine
+                    elif self.current_char == "u":
                         ident_str += self.current_char
                         self.advance()
                         if self.current_char == "n":
@@ -522,18 +474,17 @@ class Lexer:
                                                 ident_str += self.current_char
                                                 self.advance()
                                                 if self.current_char is None or self.current_char in delim23 or self.current_char in space_delim:
-                                                    tokens.append(Token(TT_BOOLLIT_TRUE, ident_str, line, pos.col)) # Boolean Literal
+                                                    tokens.append(Token(TT_BOOLLIT_TRUE, ident_str, line, pos.col))
                                                     continue
                                                 elif self.current_char not in ALPHANUM:
                                                     errors.append(LexicalError(pos, f"Invalid delimiter '{self.current_char}' after '{ident_str}'"))
                                                     self.advance()
                                                     continue
 
-                # Letter T
                 elif self.current_char == "t":
                     ident_str += self.current_char
                     self.advance()
-                    if self.current_char == "e": # tend
+                    if self.current_char == "e":
                         ident_str += self.current_char
                         self.advance()
                         if self.current_char == "n":
@@ -549,7 +500,7 @@ class Lexer:
                                     errors.append(LexicalError(pos, f"Invalid delimiter '{self.current_char}' after '{ident_str}'"))
                                     self.advance()
                                     continue
-                    elif self.current_char == "r": # tree
+                    elif self.current_char == "r":
                         ident_str += self.current_char
                         self.advance()
                         if self.current_char == "e":
@@ -558,7 +509,6 @@ class Lexer:
                             if self.current_char == "e":
                                 ident_str += self.current_char
                                 self.advance()
-                                # Tree keyword recognized - emit token
                                 if self.current_char is None or self.current_char in space_delim or self.current_char == ';':
                                     tokens.append(Token(TT_RW_TREE, ident_str, line, pos.col))
                                     continue
@@ -566,11 +516,10 @@ class Lexer:
                                     tokens.append(Token(TT_RW_TREE, ident_str, line, pos.col))
                                     continue
 
-                # Letter V
                 elif self.current_char == "v":
                     ident_str += self.current_char
                     self.advance()
-                    if self.current_char == "i": # vine
+                    if self.current_char == "i":
                         ident_str += self.current_char
                         self.advance()
                         if self.current_char == "n":
@@ -585,7 +534,7 @@ class Lexer:
                                 elif self.current_char not in ALPHANUM:
                                     tokens.append(Token(TT_RW_VINE, ident_str, line, pos.col))
                                     continue
-                    elif self.current_char == "a": # variety
+                    elif self.current_char == "a":
                         ident_str += self.current_char
                         self.advance()
                         if self.current_char == "r":
@@ -603,7 +552,6 @@ class Lexer:
                                         if self.current_char == "y":
                                             ident_str += self.current_char
                                             self.advance()
-                                            # variety introduces a case literal, written after whitespace.
                                             if self.current_char is None or self.current_char in space_delim:
                                                 tokens.append(Token(TT_RW_VARIETY, ident_str, line, pos.col))
                                                 continue
@@ -611,13 +559,11 @@ class Lexer:
                                                 errors.append(LexicalError(pos, f"Invalid delimiter '{self.current_char}' after '{ident_str}'"))
                                                 self.advance()
                                                 continue
-                                            # If followed by alphanum, continue to identifier parsing.
 
-                # Letter W
                 elif self.current_char == "w":
                     ident_str += self.current_char
                     self.advance()
-                    if self.current_char == "a": # water
+                    if self.current_char == "a":
                         ident_str += self.current_char
                         self.advance()
                         if self.current_char == "t":
@@ -636,7 +582,7 @@ class Lexer:
                                         errors.append(LexicalError(pos, f"Invalid delimiter '{self.current_char}' after '{ident_str}'"))
                                         self.advance()
                                         continue
-                    elif self.current_char == "i": # wither
+                    elif self.current_char == "i":
                         ident_str += self.current_char
                         self.advance()
                         if self.current_char == "t":
@@ -659,26 +605,19 @@ class Lexer:
                                             self.advance()
                                             continue
 
-                #Identifier            
-                maxIdentifierLength = 15 # Changed from 20 to 15
+                maxIdentifierLength = 15
                 while self.current_char is not None and self.current_char in ALPHANUM:
                     ident_str += self.current_char
                     self.advance()
 
-                # Check if identifier exceeds max length
                 if len(ident_str) > maxIdentifierLength:
-                    # Process in chunks of 15: each 15-char chunk is an error
-                    # Only the final remaining chunk (≤14 chars) is valid and added to tokens
                     i = 0
                     remaining = None
                     while i < len(ident_str):
-                        # Check if there are at least 15 characters remaining
                         if i + 15 <= len(ident_str):
-                            # 15-char chunk: generate error, don't add token
                             errors.append(LexicalError(pos, f"Identifier exceeds maximum length of {maxIdentifierLength} characters"))
                             i += 15
                         else:
-                            # Final chunk with 14 or fewer characters: valid token
                             remaining = ident_str[i:]
                             if self.current_char is None or self.current_char in idf_delim:
                                 tokens.append(Token(TT_IDENTIFIER, remaining, line, pos.col))
@@ -686,14 +625,11 @@ class Lexer:
                                 errors.append(LexicalError(pos, f"Invalid delimiter '{self.current_char}' after identifier"))
                             break
                     if remaining is None:
-                        # Length was exact multiple of 15 — all chars consumed as errors
-                        # Still create a token with the last chunk
                         last_chunk = ident_str[i - 15:] if i >= 15 else ident_str
                         if self.current_char is None or self.current_char in idf_delim:
                             tokens.append(Token(TT_IDENTIFIER, last_chunk, line, pos.col))
                     continue
                 else:
-                    # Identifier is within max length
                     if self.current_char is None or self.current_char in idf_delim:
                         tokens.append(Token(TT_IDENTIFIER, ident_str, line, pos.col))
                         continue
@@ -708,7 +644,6 @@ class Lexer:
                 pos = self.pos.copy()
                 self.advance()
                 if self.current_char == "-":
-                    # Tokenize -- as DECREMENT operator
                     ident_str += self.current_char
                     self.advance()
                     if self.current_char is not None and self.current_char not in delim25:
@@ -722,22 +657,19 @@ class Lexer:
                     self.advance()
                     tokens.append(Token(TT_MINUSEQ, ident_str, line, pos.col))
                     continue
-                # Check for valid delimiter after -
                 if self.current_char is not None and self.current_char not in set(ALPHANUM + '(~!"\' ' + '\t' + '\n'):
                     errors.append(LexicalError(pos, f"Invalid delimiter '{self.current_char}' after '{ident_str}'"))
-                    self.advance()  # Consume invalid delimiter
-                    continue  # Don't add token - eat the error
+                    self.advance()
+                    continue
                 tokens.append(Token(TT_MINUS, ident_str, line, pos.col))
                 continue
             
-            elif self.current_char == "~": # Added for negative prefix
+            elif self.current_char == "~":
                 ident_str = self.current_char
                 pos = self.pos.copy()
                 self.advance()
 
-                # If ~ is directly followed by a digit, consume the number as a negative literal
                 if self.current_char is not None and self.current_char in ZERODIGIT:
-                    # Read integer digits
                     num_str = ""
                     integer_digit_count = 0
                     while self.current_char is not None and self.current_char in ZERODIGIT:
@@ -745,7 +677,6 @@ class Lexer:
                         num_str += self.current_char
                         self.advance()
 
-                    # Check for decimal point (negative double)
                     if self.current_char == ".":
                         num_str += self.current_char
                         self.advance()
@@ -760,7 +691,6 @@ class Lexer:
                         if fractional_digit_count > 8:
                             errors.append(LexicalError(pos, f"Fractional part exceeds maximum of 8 digits"))
                             continue
-                        # Format the double
                         parts = num_str.split(".")
                         integer_part = parts[0].lstrip("0") or "0"
                         fractional_part = (parts[1] if len(parts) > 1 else "").rstrip("0") or "0"
@@ -772,7 +702,6 @@ class Lexer:
                         tokens.append(Token(TT_DOUBLELIT, ident_str, line, pos.col))
                         continue
                     else:
-                        # Negative integer
                         if integer_digit_count > 8:
                             errors.append(LexicalError(pos, f"Integer exceeds maximum of 8 digits"))
                             continue
@@ -781,8 +710,6 @@ class Lexer:
                         tokens.append(Token(TT_INTEGERLIT, ident_str, line, pos.col))
                         continue
 
-                # ~ not followed by a digit: emit as the arithmetic-negation operator.
-                # Permit a directly grouped operand, such as ~(x + 1).
                 elif self.current_char is None or self.current_char in ALPHANUM + '( \t\n':
                     tokens.append(Token(TT_NEGATIVE, ident_str, line, pos.col))
                     continue
@@ -798,7 +725,6 @@ class Lexer:
                 if self.current_char == "=":
                     ident_str += self.current_char
                     self.advance()
-                    # Check for consecutive comparison operators
                     if len(tokens) > 0 and tokens[-1].type in [TT_GT, TT_LT, TT_EQTO, TT_NOTEQ, TT_GTEQ, TT_LTEQ]:
                         errors.append(LexicalError(pos, f"Consecutive operators '{tokens[-1].value} {ident_str}' are not allowed"))
                         continue
@@ -817,11 +743,10 @@ class Lexer:
                     self.advance()
                     tokens.append(Token(TT_MODEQ, ident_str, line, pos.col))
                     continue
-                # Check for valid delimiter after %
                 if self.current_char is not None and self.current_char not in set(ALPHANUM + '(~!"\' ;' + '\t' + '\n'):
                     errors.append(LexicalError(pos, f"Invalid delimiter '{self.current_char}' after '{ident_str}'"))
-                    self.advance()  # Consume invalid delimiter
-                    continue  # Don't add token - eat the error
+                    self.advance()
+                    continue
                 tokens.append(Token(TT_MOD, ident_str, line, pos.col))
                 continue
     
@@ -835,7 +760,6 @@ class Lexer:
                     tokens.append(Token(TT_AND, ident_str, line, pos.col))
                     continue
                 else:
-                    # Emit single & token for parser to detect
                     tokens.append(Token(TT_SINGLE_AND, ident_str, line, pos.col))
                     continue
                     
@@ -860,8 +784,6 @@ class Lexer:
                 if self.current_char == "*":
                     ident_str += self.current_char
                     self.advance()
-                    # Maximal munch: '**=' must be one token (exponent-assign),
-                    # not two ('**' then '='), or downstream parsing breaks.
                     if self.current_char == "=":
                         ident_str += self.current_char
                         self.advance()
@@ -874,18 +796,16 @@ class Lexer:
                     self.advance()
                     tokens.append(Token(TT_MULTIEQ, ident_str, line, pos.col))
                     continue
-                # Check for valid delimiter after *
                 if self.current_char is not None and self.current_char not in set(ALPHANUM + '(~!"\' ' + '\t' + '\n'):
                     errors.append(LexicalError(pos, f"Invalid delimiter '{self.current_char}' after '{ident_str}'"))
-                    self.advance()  # Consume invalid delimiter
-                    continue  # Don't add token - eat the error
+                    self.advance()
+                    continue
                 tokens.append(Token(TT_MUL, ident_str, line, pos.col))
                 continue
                 
             elif self.current_char == ",":
                 ident_str = self.current_char
                 pos = self.pos.copy()
-                # Check for consecutive commas
                 if len(tokens) > 0 and tokens[-1].type == TT_COMMA:
                     errors.append(LexicalError(pos, f"Invalid delimiters ','"))
                     self.advance()
@@ -894,11 +814,6 @@ class Lexer:
                 tokens.append(Token(TT_COMMA, ident_str, line, pos.col))
                 continue
             
-            # This entire block is for a token that isn't really a token.
-            # The logic for escape sequences is handled *inside* the string and char
-            # literal parsers. This block should be removed.
-            # elif self.current_char == "\\":
-            #     ...
                 
             elif self.current_char == ";":
                 ident_str = self.current_char
@@ -945,7 +860,6 @@ class Lexer:
                     tokens.append(Token(TT_OR, ident_str, line, pos.col))
                     continue
                 else:
-                    # Emit single | token for parser to detect
                     tokens.append(Token(TT_SINGLE_OR, ident_str, line, pos.col))
                     continue
             
@@ -954,7 +868,6 @@ class Lexer:
                 pos = self.pos.copy()
                 self.advance()
                 if self.current_char == "+":
-                    # Tokenize ++ as INCREMENT operator
                     ident_str += self.current_char
                     self.advance()
                     if self.current_char is not None and self.current_char not in delim25:
@@ -972,11 +885,10 @@ class Lexer:
                         continue
                     tokens.append(Token(TT_PLUSEQ, ident_str, line, pos.col))
                     continue
-                # Check for valid delimiter after +
                 if self.current_char is not None and self.current_char not in delim24:
                     errors.append(LexicalError(pos, f"Invalid delimiter '{self.current_char}' after '{ident_str}'"))
-                    self.advance()  # Consume invalid delimiter
-                    continue  # Don't add token - eat the error
+                    self.advance()
+                    continue
                 tokens.append(Token(TT_PLUS, ident_str, line, pos.col))
                 continue
 
@@ -992,31 +904,23 @@ class Lexer:
                 tokens.append(Token(TT_LT, ident_str, line, pos.col))
                 continue
             
-            # =====================================================================
-            # EQUALS OPERATOR: = (assignment) or == (equality comparison)
-            # =====================================================================
             elif self.current_char == "=":
                 ident_str = self.current_char
                 pos = self.pos.copy()
                 self.advance()
                 
-                if self.current_char == "=":  # Check for second '='
+                if self.current_char == "=":
                     ident_str += self.current_char
                     self.advance()
                     
-                    # Don't check for third '=' - let it tokenize as separate '=' token
-                    # Parser will detect the pattern '==' followed by '='
                     
-                    # Prevent consecutive comparison operators (e.g., "< ==" or "> ==")
                     if len(tokens) > 0 and tokens[-1].type in [TT_GT, TT_LT, TT_EQTO, TT_NOTEQ, TT_GTEQ, TT_LTEQ]:
                         errors.append(LexicalError(pos, f"invalid delimiters '{tokens[-1].value} {ident_str}' are not allowed"))
                         continue
                     
-                    # Valid '==' (equality comparison operator)
                     tokens.append(Token(TT_EQTO, ident_str, line, pos.col))
                     continue
                 
-                # Single '=' (assignment operator)
                 tokens.append(Token(TT_EQ, ident_str, line, pos.col))
                 continue
 
@@ -1027,13 +931,11 @@ class Lexer:
                 if self.current_char == "=":
                     ident_str += self.current_char
                     self.advance()
-                    # Check for consecutive comparison operators
                     if len(tokens) > 0 and tokens[-1].type in [TT_GT, TT_LT, TT_EQTO, TT_NOTEQ, TT_GTEQ, TT_LTEQ]:
                         errors.append(LexicalError(pos, f"invalid delimiters '{tokens[-1].value} {ident_str}' are not allowed"))
                         continue
                     tokens.append(Token(TT_GTEQ, ident_str, line, pos.col))
                     continue
-                # Check for consecutive comparison operators
                 if len(tokens) > 0 and tokens[-1].type in [TT_GT, TT_LT, TT_EQTO, TT_NOTEQ, TT_GTEQ, TT_LTEQ]:
                     errors.append(LexicalError(pos, f"invalid delimiters '{tokens[-1].value} {ident_str}' are not allowed"))
                     continue
@@ -1070,45 +972,36 @@ class Lexer:
                     self.advance()
                 continue
 
-            # =====================================================================
-            # FORWARD SLASH: / (division), // (comment), /* */ (multi-line comment), /= (divide-assign)
-            # =====================================================================
             elif self.current_char == "/":
                 ident_str = self.current_char
                 pos = self.pos.copy()
                 self.advance()
                 
-                if self.current_char == "/":  # Single-line comment: // comment text
+                if self.current_char == "/":
                     ident_str += self.current_char
                     self.advance()
-                    # Consume all characters until end of line or file
                     while self.current_char is not None and self.current_char != "\n":
                         ident_str += self.current_char
                         self.advance()
-                    # Comments are NOT added to tokens (they are skipped)
                     continue
                     
-                elif self.current_char == "*":  # Multi-line comment: /* comment text */
+                elif self.current_char == "*":
                     ident_str += self.current_char
                     self.advance()
                     found_close = False
-                    # Consume all characters until closing */
                     while self.current_char is not None:
-                        # Check for closing */ sequence
                         if self.current_char == "*" and self.pos.index + 1 < len(self.source_code) and self.source_code[self.pos.index + 1] == "/":
                             ident_str += "*/"
-                            self.advance()  # Skip *
-                            self.advance()  # Skip /
+                            self.advance()
+                            self.advance()
                             found_close = True
                             break
                         else:
                             ident_str += self.current_char
-                            if self.current_char == "\n":  # Track line numbers inside comment
+                            if self.current_char == "\n":
                                 line += 1
                             self.advance()
-                    # Comments are NOT added to tokens (they are skipped)
                     
-                    # Error if comment was never closed
                     if not found_close:
                         errors.append(LexicalError(pos, f"Missing closing '*/' after '{ident_str}'"))
                         continue
@@ -1119,11 +1012,10 @@ class Lexer:
                     tokens.append(Token(TT_DIVEQ, ident_str, line, pos.col))
                     continue
                 else:
-                    # Check for valid delimiter after /
                     if self.current_char is not None and self.current_char not in set(ALPHANUM + '(~!"\' ' + '\t' + '\n'):
                         errors.append(LexicalError(pos, f"Invalid delimiter '{self.current_char}' after '{ident_str}'"))
-                        self.advance()  # Consume invalid delimiter
-                        continue  # Don't add token - eat the error
+                        self.advance()
+                        continue
                     tokens.append(Token(TT_DIV, ident_str, line, pos.col))
                     continue
             
@@ -1142,7 +1034,6 @@ class Lexer:
                         if len(fractional_part + self.current_char) > 8: 
                             errors.append(LexicalError(pos, f"'{ident_str}' exceeds maximum number of decimal places"))
                             overflow = True
-                            # Consume remaining digits to avoid cascading errors
                             while self.current_char is not None and self.current_char in ZERODIGIT:
                                 self.advance()
                             break
@@ -1169,142 +1060,104 @@ class Lexer:
                 tokens.append(Token(TT_COLON, ident_str, line, pos.col))
                 continue
 
-            # =====================================================================
-            # 
-            # 
-            # =====================================================================
             elif self.current_char in ZERODIGIT:
-                dot_count = 0               # Count decimal points (max 1)
-                ident_str = ""              # Build the number string
-                pos = self.pos.copy()       # Save position for errors
-                integer_digit_count = 0     # Count digits before decimal (max 15)
-                fractional_digit_count = 0  # Count digits after decimal (max 8)
-                has_e = False               # Track if scientific notation (e.g., 1e10)
+                dot_count = 0
+                ident_str = ""
+                pos = self.pos.copy()
+                integer_digit_count = 0
+                fractional_digit_count = 0
+                has_e = False
 
                 
-                # Read all digits before decimal point
                 while self.current_char is not None and self.current_char in ZERODIGIT:
                     integer_digit_count += 1
                     ident_str += self.current_char
                     self.advance()
 
-                # Step 2: Check for decimal point (converts to double/float)
                 if self.current_char == ".":
-                    # For decimals, check if integer part exceeds 15 digits
                     if integer_digit_count > 15:
-                        # Process integer part in chunks of 15: each 15-digit chunk is an error
-                        # Only the final remaining chunk (≤15 digits) continues to decimal processing
                         integer_part = ident_str
                         i = 0
                         while i < len(integer_part):
                             if i + 15 < len(integer_part):
-                                # More than 15 digits remain: generate error for this chunk
                                 errors.append(LexicalError(pos, f"Integer part of decimal exceeds maximum of 15 digits"))
                                 i += 15
                             else:
-                                # Final chunk with 15 or fewer digits — valid
                                 ident_str = integer_part[i:]
                                 break
                         else:
-                            # All digits consumed as errors, no valid remainder
                             ident_str = "0"
-                    dot_count = 1  # Mark that we found a decimal point
+                    dot_count = 1
                     ident_str += self.current_char
                     self.advance()
                     
-                    # After decimal point, must have at least one digit (e.g., "3." is invalid)
                     if self.current_char is None or self.current_char not in ZERODIGIT:
                         errors.append(LexicalError(pos, f"Invalid number '{ident_str}': decimal point must be followed by digits"))
                         continue
                     
-                    # Read fractional part (digits after decimal point)
                     fractional_part = ""
                     while self.current_char is not None and self.current_char in ZERODIGIT:
                         fractional_digit_count += 1
                         fractional_part += self.current_char
                         self.advance()
                     
-                    # Check if fractional part exceeds 8 digits
                     if fractional_digit_count > 8:
-                        # Process in chunks of 8: each 8-digit chunk is an error
-                        # Only the final remaining chunk (≤8 digits) is added to the number
                         i = 0
                         final_fractional = ""
                         while i < len(fractional_part):
                             if i + 8 < len(fractional_part):
-                                # More than 8 digits remain: generate error for this chunk
                                 errors.append(LexicalError(pos, f"Fractional part exceeds maximum of 8 digits"))
                                 i += 8
                             else:
-                                # Final chunk with 8 or fewer digits — valid
                                 final_fractional = fractional_part[i:]
                                 break
                         ident_str += final_fractional
                     else:
                         ident_str += fractional_part
 
-                # Handle integers longer than 8 digits
-                # Process in chunks of 8: each chunk beyond the valid last ≤8 digits is an error
                 if dot_count == 0 and integer_digit_count > 8:
                     i = 0
                     remaining = None
                     while i < len(ident_str):
-                        # Check if more than 8 characters remain
                         if i + 8 < len(ident_str):
-                            # More than 8 digits remain: generate error for this chunk
                             errors.append(LexicalError(pos, f"Integer exceeds maximum of 8 digits"))
                             i += 8
                         else:
-                            # Final chunk with 8 or fewer digits: valid token
                             remaining = ident_str[i:]
-                            # Strip leading zeros for the remaining valid portion
                             remaining = remaining.lstrip("0") or "0"
                             tokens.append(Token(TT_INTEGERLIT, remaining, line, pos.col))
                             break
                     if remaining is None:
-                        # Safety fallback (should not happen with the corrected condition)
                         tokens.append(Token(TT_INTEGERLIT, "0", line, pos.col))
                     continue
                 
                 if fractional_digit_count > 8:
-                    # Error already reported and fractional part already truncated above.
-                    # Fall through to create a token with the truncated valid portion.
                     pass
 
-                # Step 3: Check for scientific notation (e.g., 1.5e10, 2.3e-5)
-                # Only valid for doubles (must have decimal point)
                 if self.current_char is not None and self.current_char in 'eE' and dot_count == 1:
                     has_e = True
                     ident_str += self.current_char
                     self.advance()
                     
-                    # Handle optional sign after 'e' (e.g., 1.2e-5 or 1.2e+5)
                     if self.current_char in '+-':
                         ident_str += self.current_char
                         self.advance()
                     
-                    # Must have digits after 'e' (e.g., "1.5e" is invalid)
                     if self.current_char is None or self.current_char not in ZERODIGIT:
                         errors.append(LexicalError(pos, f"Invalid scientific notation: 'e' must be followed by digits."))
                         continue
                     
-                    # Read exponent digits
                     while self.current_char is not None and self.current_char in ZERODIGIT:
                         ident_str += self.current_char
                         self.advance()
 
                 if dot_count == 0 and not has_e:
-                    # Integer literal - type checking is done by the parser (SYNTAX error)
                     
-                    # Check for valid delimiter after integer
                     if self.current_char is not None and self.current_char not in whlnum_delim:
-                        # Strip leading zeros and tokenize the valid integer first
                         valid_int = ident_str.lstrip("0") or "0"
                         tokens.append(Token(TT_INTEGERLIT, valid_int, line, pos.col))
                         
-                        # Check if followed by letter (not underscore or digit)
                         if self.current_char in ALPHA:
-                            # Peek ahead to see if it's a reserved word
                             temp_str = ''
                             temp_pos = self.pos.copy()
                             temp_char = self.current_char
@@ -1313,7 +1166,6 @@ class Lexer:
                                 temp_pos.advance(temp_char)
                                 temp_char = self.source_code[temp_pos.index] if temp_pos.index < len(self.source_code) else None
                             
-                            # Check if it's a reserved word
                             reserved_words = {'water', 'plant', 'seed', 'leaf', 'branch', 'tree', 'spring', 'wither', 'bud', 
                                             'harvest', 'grow', 'cultivate', 'tend', 'empty', 'prune', 'skip', 'reclaim', 
                                             'root', 'pollinate', 'variety', 'fertile', 'soil', 'bundle', 'string', 'vine', 'sunshine', 'frost'}
@@ -1323,14 +1175,11 @@ class Lexer:
                             else:
                                 errors.append(LexicalError(pos, f"Identifiers cannot start with a number: '{ident_str}{self.current_char}...'"))
                             
-                            # Consume the rest of the invalid identifier
                             while self.current_char is not None and self.current_char in ALPHANUM:
                                 self.advance()
                         elif self.current_char == '_':
-                            # Check if underscore is followed by letters (reserved word or identifier)
                             temp_index = self.pos.index + 1
                             if temp_index < len(self.source_code) and self.source_code[temp_index] in ALPHA:
-                                # Peek ahead to see if it's a reserved word
                                 temp_str = ''
                                 while temp_index < len(self.source_code) and self.source_code[temp_index] in ALPHANUM:
                                     temp_str += self.source_code[temp_index]
@@ -1345,69 +1194,56 @@ class Lexer:
                                 else:
                                     errors.append(LexicalError(pos, f"Identifiers cannot start with a number: '{ident_str}_...'"))
                                 
-                                # Consume underscore and the rest
                                 while self.current_char is not None and self.current_char in ALPHANUM:
                                     self.advance()
                             else:
-                                # Underscore followed by digits - numeric separator error
                                 errors.append(LexicalError(pos, f"Underscore cannot be used in numeric literals"))
-                                # Consume underscore and any following digits/underscores/letters
                                 while self.current_char is not None and self.current_char in ALPHANUM:
                                     self.advance()
                         else:
-                            # Invalid delimiter error already added when integer was tokenized
                             errors.append(LexicalError(pos, f"Invalid delimiter '{self.current_char}' after '{ident_str}'"))
-                            # Don't consume the character - let the main loop handle it
                         continue
                     
                     ident_str = ident_str.lstrip("0") or "0"
                     tokens.append(Token(TT_INTEGERLIT, ident_str, line, pos.col))
                     continue
                     
-                else:  # Float case
-                    # Check for valid delimiter after double
+                else:
                     if self.current_char is not None and self.current_char not in decim_delim:
                         errors.append(LexicalError(pos, f"Invalid delimiter '{self.current_char}' after '{ident_str}'"))
                         self.advance()
                         continue
-                    if not has_e: # Only re-format if not scientific notation
+                    if not has_e:
                          parts = ident_str.split(".")
                          integer_part = parts[0].lstrip("0") or "0"
                          fractional_part = (parts[1] if len(parts) > 1 else "").rstrip("0") or "0"
                          if fractional_part == "0":
-                             ident_str = f"{integer_part}.0" # Keep at least one zero
+                             ident_str = f"{integer_part}.0"
                          else:
                              ident_str = f"{integer_part}.{fractional_part}"
 
                     tokens.append(Token(TT_DOUBLELIT, ident_str, line, pos.col))
                     continue
 
-            # =====================================================================
-            # STRING LITERAL PARSING: "hello world"
-            # Supports escape sequences: \n (newline), \t (tab), \{ \} (literal braces)
-            # =====================================================================
             elif self.current_char == '"':
-                string = ''              # Full string including quotes
-                pos = self.pos.copy()    # Save position for error reporting
-                escape_character = False # Track if we're processing an escape sequence
-                string += self.current_char  # Include opening quote
+                string = ''
+                pos = self.pos.copy()
+                escape_character = False
+                string += self.current_char
                 self.advance()
 
-                # Supported escape sequences
                 escape_characters = {
-                    'n': '\n',   # Newline
-                    't': '\t',   # Tab
-                    '{': '\\{',  # Literal left brace
-                    '}': '\\}',  # Literal right brace
-                    '"': '"',    # Escaped double quote
-                    '\\': '\\',  # Escaped backslash
+                    'n': '\n',
+                    't': '\t',
+                    '{': '\\{',
+                    '}': '\\}',
+                    '"': '"',
+                    '\\': '\\',
                 }
 
                 has_string_error = False
-                # Read until closing quote (or end of file)
                 while self.current_char is not None and (self.current_char != '"' or escape_character):
                     if escape_character:
-                        # Process escape sequence (e.g., \n becomes newline)
                         if self.current_char in escape_characters:
                             string += escape_characters[self.current_char]
                         else:
@@ -1424,7 +1260,6 @@ class Lexer:
                     self.advance()
 
                 if has_string_error:
-                    # Consume rest of string to avoid cascading errors
                     while self.current_char is not None and self.current_char != '"':
                         self.advance()
                     if self.current_char == '"':
@@ -1435,7 +1270,6 @@ class Lexer:
                     string += self.current_char
                     self.advance()
                 else:
-                    # Missing closing quote - report error and skip (don't create token)
                     errors.append(LexicalError(pos, f"Missing closing '\"' for string literal"))
                     continue
 
@@ -1444,48 +1278,36 @@ class Lexer:
                     self.advance()
                     continue
             
-                # Token stores the REAL characters (like C compilers do).
-                # Display escaping is handled separately in the server.
                 tokens.append(Token(TT_STRINGLIT, string, line, pos.col))
                 continue
     
-            # =====================================================================
-            # CHARACTER LITERAL PARSING: 'a', '\n', '\t'
-            # Single character enclosed in single quotes
-            # =====================================================================
             elif self.current_char == "'":
-                string = ''          # Full text including quotes (for display)
-                char = ''            # Actual character value
+                string = ''
+                char = ''
                 pos = self.pos.copy()
-                string += self.current_char  # Include opening quote
+                string += self.current_char
                 self.advance()
-                has_error = False    # Track if an error was already reported
+                has_error = False
 
-                # Skip leading whitespace
                 while self.current_char is not None and self.current_char in ' \t':
                     string += self.current_char
                     self.advance()
 
-                # Read until closing quote (or end of file/line)
                 while self.current_char is not None and self.current_char != "'":
-                    if self.current_char == '\n':  # Newline breaks character literal
+                    if self.current_char == '\n':
                         break
-                    elif self.current_char == '\\':  # Escape sequence
-                        # Handle escape sequences for characters
+                    elif self.current_char == '\\':
                         string += self.current_char
                         self.advance()
                         if self.current_char is None:
-                            break # Will be caught as a missing closing quote
+                            break
                         
-                        # Only allow valid escape sequences
                         if self.current_char in "'\\nt": 
                             char += f"\\{self.current_char}"
                             string += self.current_char
                         else:
-                            # Invalid escape sequence - report error
                             errors.append(LexicalError(pos, f"Invalid escape sequence '\\{self.current_char}' in character literal"))
                             has_error = True
-                            # Consume rest of char literal to avoid cascading errors
                             while self.current_char is not None and self.current_char != "'":
                                 self.advance()
                             if self.current_char == "'":
@@ -1496,11 +1318,9 @@ class Lexer:
                         char += self.current_char
                     self.advance()
                 
-                # Skip trailing whitespace before closing quote
                 while len(char) > 0 and char[-1] in ' \t':
                     char = char[:-1]
 
-                # Skip further processing if we already reported an error
                 if has_error:
                     continue
 
@@ -1508,7 +1328,6 @@ class Lexer:
                     string += self.current_char
                     self.advance()
                 else:
-                    # Missing closing quote - report error and skip (don't create token)
                     errors.append(LexicalError(pos, f"Missing closing quote for character literal"))
                     continue
 
@@ -1517,15 +1336,11 @@ class Lexer:
                     self.advance()
                     continue
 
-                # Character literal must contain exactly one character (or one escape sequence)
-                # Strip quotes to get inner content
                 inner = char.strip()
                 if len(inner) == 0:
-                    # Empty char literal '' defaults to a space character
                     string = "' '"
                     inner = ' '
                 elif inner.startswith('\\') and len(inner) == 2:
-                    # Valid escape sequence like \n, \t
                     pass
                 elif len(inner) > 1:
                     errors.append(LexicalError(pos, f"Character literal must contain exactly one character, found '{inner}'"))
@@ -1538,7 +1353,6 @@ class Lexer:
                 pos = self.pos.copy()
                 ident_str = self.current_char
                 self.advance()
-                # Check for valid delimiter after `
                 if self.current_char is not None and self.current_char not in set(ALPHANUM + '(~!"\' ' + '\t' + '\n'):
                     errors.append(LexicalError(pos, f"Invalid delimiter '{self.current_char}' after '{ident_str}'"))
                     self.advance()
@@ -1550,12 +1364,9 @@ class Lexer:
                 pos = self.pos.copy()
                 char = self.current_char
                 
-                # Special handling for underscore followed by alphanumeric
                 if char == '_':
                     self.advance()
-                    # Check if followed by letters (reserved word or identifier)
                     if self.current_char is not None and self.current_char in ALPHA:
-                        # Peek ahead to see if it's a reserved word
                         temp_str = ''
                         temp_index = self.pos.index
                         while temp_index < len(self.source_code) and self.source_code[temp_index] in ALPHANUM:
@@ -1571,7 +1382,6 @@ class Lexer:
                         else:
                             errors.append(LexicalError(pos, f"Identifiers cannot start with a symbol: '_...'"))
                         
-                        # Consume the rest
                         while self.current_char is not None and self.current_char in ALPHANUM:
                             self.advance()
                         continue
@@ -1583,47 +1393,21 @@ class Lexer:
                     errors.append(LexicalError(pos, f"Illegal Character '" + char + "'"))
                     continue
                 
-        # End of file reached - add EOF token
         if self.current_char is None:
             tokens.append(Token(TT_EOF, "", line, pos.col))
         
-        return tokens, errors  # Return tuple: (list of tokens, list of errors)
+        return tokens, errors
 
-# ============================================================================
-# HELPER FUNCTIONS - Public interface for using the lexer
-# ============================================================================
 
 def run(source_code):
-    """
-    Legacy function - runs lexer and returns tokens and errors.
-    
-    Args:
-        source_code (str): GAL source code to tokenize
-    
-    Returns:
-        tuple: (tokens, errors) where both are lists
-    """
     lexer = Lexer(source_code)
     tokens, error = lexer.make_tokens()
     return tokens, error
 
 def lex(source_code):
-    """
-    Main entry point for lexical analysis (used by server.py).
-    Tokenizes source code and converts errors to strings.
-    
-    Args:
-        source_code (str): GAL source code to tokenize
-    
-    Returns:
-        tuple: (tokens, str_errors) where:
-            - tokens: list of Token objects
-            - str_errors: list of error messages as strings
-    """
     lexer = Lexer(source_code)
     tokens, errors = lexer.make_tokens()
     
-    # Convert LexicalError objects to string messages
     str_errors = []
     for e in errors:
         try:

Backend/parser/__init__.py

@@ -1,12 +1,2 @@
-# ============================================================================
-# PARSER PACKAGE - Public API for syntax analysis + AST construction
-# ============================================================================
-# Re-exports LL1Parser so external callers (server.py) can keep using:
-#     from parser import LL1Parser
-# unchanged after the restructure.
-#
-# In a later phase (5b), parser/builder.py will hold build_ast and the parser
-# will import it as a sibling rather than reaching across to GALsemantic.py.
-# ============================================================================
 
 from .parser import LL1Parser  # noqa: F401  - main public class

Backend/parser/builder.py

@@ -1,36 +1,12 @@
-# ============================================================================
-# AST BUILDER - build_ast + all parse_* helpers + analyze_semantics
-# ============================================================================
-# Extracted from GALsemantic.py during the modular restructure.
-#
-# This module turns a validated token stream into an AST. The parser (in
-# parser/parser.py) does LL(1) syntax checking, then hands the tokens to
-# build_ast() here. During construction the parse_* helpers also perform
-# many semantic checks (undeclared variables, duplicate functions, type
-# mismatches in expressions). A dedicated tree-walking validator in
-# semantic/analyzer.py runs as the final semantic pass.
-#
-# Why this lives under parser/ and not semantic/:
-#   The natural output of parsing is an AST. Putting build_ast under parser/
-#   makes the data flow textbook-clean:
-#       tokens -> parser (syntax + AST construction) -> semantic (validate)
-#   This is more correct than the original layout where GALsemantic.py was
-#   doing both jobs.
-# ============================================================================
 import copy
 import re
 
-# Shared types & constants
 from shared.tokens import *  # noqa: F401,F403 - TT_* constants used throughout parse_*
 from semantic.errors import SemanticError
 from shared.ast_nodes import *  # noqa: F401,F403 - all AST node classes
-# SymbolTable lives in semantic/symbol_table.py.
 from semantic.symbol_table import SymbolTable
 
 
-# Vestigial placeholder from an earlier design; the real semantic checks happen
-# in the parse_* helpers below and in semantic/analyzer.py. Kept (locally) only
-# because semantic_analyzer is referenced as a module-level singleton.
 class SemanticAnalyzer:
     def __init__(self, symbol_table):
         self.symbol_table = symbol_table
@@ -41,26 +17,14 @@ symbol_table = SymbolTable()
 semantic_analyzer = SemanticAnalyzer(symbol_table)
 context_stack = []
 
-# ============================================================================
-# BUILD AST - Main entry point for AST construction
-# ============================================================================
-# Walks the token stream produced by the lexer (after parser validation)
-# and constructs a tree of ASTNode objects. While walking it also performs
-# many semantic checks via the parse_* helpers below (undeclared variables,
-# duplicate functions, type mismatches in expressions, etc.).
-#
-# Called by Gal_Parser.parse_and_build right after LL(1) syntax validation.
-# Returns the root ProgramNode. Errors are raised as SemanticError.
-# ============================================================================
 
 def build_ast(tokens):
-    """Constructs an AST from the token list after LL(1) parsing."""
     root = ProgramNode()
-    symbol_table.variables = {}  # Stores variables 
-    symbol_table.functions = {}  # Stores function definitions
+    symbol_table.variables = {}
+    symbol_table.functions = {}
     symbol_table.scopes = [{}] 
     symbol_table.function_variables = {}
-    symbol_table.bundle_types = {}  # Reset bundle type definitions
+    symbol_table.bundle_types = {}
     context_stack = []
     index = 0
     symbol_table.current_func_name = None
@@ -68,7 +32,6 @@ def build_ast(tokens):
     while index < len(tokens):
         token = tokens[index]
 
-        # Skip semicolons between top-level declarations
         if token.type == ";":
             index += 1
             continue
@@ -112,7 +75,6 @@ def build_ast(tokens):
                     root.add_child(node)
 
             elif tokens[index].type == "id" and tokens[index].value in symbol_table.bundle_types:
-                # Bundle return type: pollinate Pair makePair(...) { ... }
                 id_type = tokens[index].value
                 index += 1
                 if tokens[index].type != "id":
@@ -147,11 +109,10 @@ def build_ast(tokens):
 
         elif token.value == "bundle":
             bundle_name = tokens[index + 1].value
-            index += 2  # skip 'bundle' and bundle name
+            index += 2
 
             if tokens[index].type == "{":
-                # Bundle definition: bundle Person { seed age; vine name; }
-                index += 1  # skip '{'
+                index += 1
                 members = {}
                 while tokens[index].type != "}":
                     if tokens[index].value in {"seed", "tree", "vine", "leaf", "branch"}:
@@ -160,22 +121,21 @@ def build_ast(tokens):
                         if member_name in members:
                             raise SemanticError(f"Semantic Error: Duplicate member '{member_name}' in bundle '{bundle_name}'.", tokens[index].line)
                         members[member_name] = member_type
-                        index += 2  # skip type and name
+                        index += 2
                         if tokens[index].type == ";":
-                            index += 1  # skip ';'
+                            index += 1
                     elif tokens[index].type == "id" and tokens[index].value in symbol_table.bundle_types:
-                        # Nested bundle member: Address addr;
                         member_type = tokens[index].value
                         member_name = tokens[index + 1].value
                         if member_name in members:
                             raise SemanticError(f"Semantic Error: Duplicate member '{member_name}' in bundle '{bundle_name}'.", tokens[index].line)
                         members[member_name] = member_type
-                        index += 2  # skip type and name
+                        index += 2
                         if tokens[index].type == ";":
-                            index += 1  # skip ';'
+                            index += 1
                     else:
                         raise SemanticError(f"Semantic Error: Invalid member type '{tokens[index].value}' in bundle definition.", tokens[index].line)
-                index += 1  # skip '}'
+                index += 1
 
                 if bundle_name in symbol_table.bundle_types:
                     raise SemanticError(f"Semantic Error: Bundle type '{bundle_name}' already defined.", token.line)
@@ -185,7 +145,6 @@ def build_ast(tokens):
                 root.add_child(node)
 
             else:
-                # Global bundle variable: bundle Person p;
                 var_name = tokens[index].value
                 index += 1
 
@@ -233,12 +192,6 @@ def parse_functionOrVariable(tokens, index):
     
     return None, index
 
-# ============================================================================
-# DECLARATION PARSERS - parse_function, parse_variable
-# These build the AST nodes for top-level declarations and register them
-# in the symbol table. parse_function handles both root() and pollinate
-# functions; parse_variable handles seed/tree/leaf/branch/vine declarations.
-# ============================================================================
 def parse_function(tokens, index, func_name, func_type):
     line = tokens[index].line
 
@@ -252,12 +205,10 @@ def parse_function(tokens, index, func_name, func_type):
         error = f"Semantic Error: '{func_name}' already declared."
         raise SemanticError(error, tokens[index].line)
 
-    # Entry point: root()  (legacy alias: skibidi{...})
     if func_name in {"root"}:
         symbol_table.enter_scope()
-        index += 1  # consume keyword
+        index += 1
 
-        # root() requires empty parameter list
         if tokens[index].type == "(":
             index += 1
             if tokens[index].type != ")":
@@ -289,13 +240,12 @@ def parse_function(tokens, index, func_name, func_type):
                     param_node.add_child(ASTNode("Identifier", param_name))
                     index += 1
 
-                    # Check for array parameter: seed arr[]
                     is_list = False
                     if tokens[index].type == "[":
-                        index += 1  # skip '['
+                        index += 1
                         if tokens[index].type != "]":
                             raise SemanticError(f"Semantic Error: Expected ']' after '[' in array parameter.", line)
-                        index += 1  # skip ']'
+                        index += 1
                         is_list = True
                         param_node.add_child(ASTNode("ArrayParam", "true"))
 
@@ -312,7 +262,6 @@ def parse_function(tokens, index, func_name, func_type):
                     raise SemanticError(error, line)
 
             elif tokens[index].type == "id" and tokens[index].value in symbol_table.bundle_types:
-                # Bundle parameter: Pair p
                 param_type = tokens[index].value
                 index += 1
                 if tokens[index].type == "id":
@@ -401,17 +350,17 @@ def parse_variable(tokens, index, var_name, var_type):
 
             elif tokens[index].value == "water":
                 water_line = tokens[index].line
-                index += 1  # skip 'water'
+                index += 1
                 if tokens[index].type != "(":
                     raise SemanticError(f"Semantic Error: Expected '(' after water.", water_line)
-                index += 1  # skip '('
+                index += 1
                 water_type = None
                 if tokens[index].value in {"seed", "tree", "leaf", "branch", "vine"}:
                     water_type = tokens[index].value
                     index += 1
                 if tokens[index].type != ")":
                     raise SemanticError(f"Semantic Error: water() accepts only an optional type parameter (e.g., water(seed)).", water_line)
-                index += 1  # skip ')'
+                index += 1
                 if water_type and not _types_compatible(var_type, water_type):
                     raise SemanticError(f"Semantic Error: Type mismatch — cannot assign water({water_type}) to '{var_type}' variable.", water_line)
                 value_node = ASTNode("Input", f"water({water_type})" if water_type else "water()", line=water_line)
@@ -422,24 +371,21 @@ def parse_variable(tokens, index, var_name, var_type):
                 var_node.add_child(value_node)
 
         elif tokens[index].type == "[":
-            # List declaration with size: seed nums[3]; or seed nums[];
-            # Also supports multi-dimensional: seed matrix[2][3];
             is_list = True
             dimensions = []
             while tokens[index].type == "[":
-                index += 1  # skip '['
+                index += 1
                 dim_size = 0
                 if tokens[index].type == "dbllit":
                     raise SemanticError(f"Semantic Error: Array size must be of type 'seed' (integer), got 'tree' (float) '{tokens[index].value}'.", line)
                 if tokens[index].type == "intlit":
                     dim_size = int(tokens[index].value)
-                    index += 1  # skip size
+                    index += 1
                 if tokens[index].type != "]":
                     raise SemanticError(f"Syntax Error: Expected ']' after list size.", line)
-                index += 1  # skip ']'
+                index += 1
                 dimensions.append(dim_size)
 
-            # Build nested List nodes for multi-dimensional arrays
             default_literals = {"seed": "0", "tree": "0.0", "leaf": "''", "vine": '""', "branch": "false"}
 
             def build_list_node(dims):
@@ -455,26 +401,23 @@ def parse_variable(tokens, index, var_name, var_type):
             list_node = build_list_node(dimensions)
             var_node.add_child(list_node)
 
-            # Handle optional initialization after size: seed nums[3] = {10, 20, 30} ;
             if tokens[index].type == "=":
-                index += 1  # skip '='
+                index += 1
                 if tokens[index].type == "{":
-                    index += 1  # skip '{'
+                    index += 1
                     elements = []
                     while tokens[index].type != "}":
                         expr, index = parse_expression_type(tokens, index, var_type)
                         elements.append(expr)
                         if tokens[index].type == ",":
                             index += 1
-                    index += 1  # skip '}'
+                    index += 1
                     value_node = ListNode(elements=elements, line=line)
-                    # Replace the default list_node with the initialized values
                     var_node.children[-1] = value_node
                 else:
                     raise SemanticError(f"Syntax Error: Expected '{{' after '=' in array initialization.", line)
    
         else:
-            # Uninitialized declaration: vine name; or seed x;
             pass
 
         error = symbol_table.declare_variable(var_name, var_type, is_list = is_list)
@@ -502,30 +445,20 @@ def parse_variable(tokens, index, var_name, var_type):
 
 
 def _skip_semicolons(tokens, index):
-    """Advance past any consecutive ';' tokens."""
     while index < len(tokens) and tokens[index].type == ";":
         index += 1
     return index
 
 
-# ============================================================================
-# STATEMENT PARSER - The big dispatch
-# Walks one statement at a time inside a function body. Recognizes every
-# statement form: variable declaration, assignment, function call,
-# spring/bud/wither, grow/cultivate/tend, harvest, plant, water,
-# reclaim, prune, skip. Returns (ast_node, new_index).
-# ============================================================================
 def parse_statement(tokens, index, func_type = None):
     token = tokens[index]
 
-    # Skip stray semicolons before the actual statement
     if token.type == ";":
         return None, index + 1
 
     line = token.line
 
     if token.value in {"seed", "tree", "vine", "leaf", "branch"}:
-        # Normalize GAL type keywords to internal types
         var_type = token.value
         var_name = tokens[index + 1].value
         index += 2
@@ -539,30 +472,27 @@ def parse_statement(tokens, index, func_type = None):
         return node, index
 
     elif token.value == "bundle":
-        # Local bundle variable declaration: bundle Person p; or bundle Person p[2];
         bundle_type_name = tokens[index + 1].value
         if bundle_type_name not in symbol_table.bundle_types:
             raise SemanticError(f"Semantic Error: Bundle type '{bundle_type_name}' is not defined.", token.line)
         var_name = tokens[index + 2].value
-        index += 3  # skip 'bundle', type name, var name
+        index += 3
 
         members = symbol_table.bundle_types[bundle_type_name]
         _defaults = {"seed": 0, "tree": 0.0, "leaf": '', "vine": "", "branch": False}
 
         if tokens[index].type == "[":
-            # Array of bundles: bundle Point p[2];
-            index += 1  # skip '['
+            index += 1
             if tokens[index].type == "dbllit":
                 raise SemanticError(f"Semantic Error: Array size must be of type 'seed' (integer), got 'tree' (float) '{tokens[index].value}'.", token.line)
             array_size = 0
             if tokens[index].type == "intlit":
                 array_size = int(tokens[index].value)
-                index += 1  # skip size
+                index += 1
             if tokens[index].type != "]":
                 raise SemanticError(f"Syntax Error: Expected ']' after array size.", token.line)
-            index += 1  # skip ']'
+            index += 1
 
-            # Build list of bundle default values
             list_node = ASTNode("List", line=token.line)
             for _ in range(array_size):
                 bundle_val_node = ASTNode("BundleDefault", line=token.line)
@@ -625,17 +555,15 @@ def parse_statement(tokens, index, func_type = None):
                         list_access_node, index = parse_list_access(tokens, index)
 
                         if tokens[index + 1].type == "." and var_type in symbol_table.bundle_types:
-                            # Bundle array member assignment: p[0].x = 1; or p[0].addr.zip = 1;
-                            index += 2  # skip ']' and '.'
+                            index += 2
                             member_name = tokens[index].value
                             bundle_members = symbol_table.bundle_types[var_type]
                             if member_name not in bundle_members:
                                 raise SemanticError(f"Semantic Error: Bundle type '{var_type}' has no member '{member_name}'.", line)
                             member_type = bundle_members[member_name]
                             target = ArrayMemberAccessNode(list_access_node, member_name, line=line)
-                            index += 1  # skip member name
+                            index += 1
 
-                            # Handle chained access for nested bundles: p[0].addr.zip
                             while tokens[index].type == "." and member_type in symbol_table.bundle_types:
                                 next_member = tokens[index + 1].value
                                 nested_members = symbol_table.bundle_types[member_type]
@@ -643,10 +571,10 @@ def parse_statement(tokens, index, func_type = None):
                                     raise SemanticError(f"Semantic Error: Bundle type '{member_type}' has no member '{next_member}'.", line)
                                 member_type = nested_members[next_member]
                                 target = MemberAccessNode(target, next_member, line=line)
-                                index += 2  # skip '.', member
+                                index += 2
 
                             if tokens[index].type == "=":
-                                index += 1  # skip '='
+                                index += 1
                                 value_node, index = parse_expression_type(tokens, index, member_type)
                                 assign_node = AssignmentNode(target, value_node, line=line)
                                 assignments_node.add_child(assign_node)
@@ -667,17 +595,17 @@ def parse_statement(tokens, index, func_type = None):
                             index += 2 
                             if tokens[index].value == "water":
                                 water_line = tokens[index].line
-                                index += 1  # skip 'water'
+                                index += 1
                                 if tokens[index].type != "(":
                                     raise SemanticError(f"Syntax Error: Expected '(' after water.", water_line)
-                                index += 1  # skip '('
+                                index += 1
                                 water_type = None
                                 if tokens[index].value in {"seed", "tree", "leaf", "branch", "vine"}:
                                     water_type = tokens[index].value
                                     index += 1
                                 if tokens[index].type != ")":
                                     raise SemanticError(f"Semantic Error: water() accepts only an optional type parameter.", water_line)
-                                index += 1  # skip ')'
+                                index += 1
                                 if water_type and not _types_compatible(var_type, water_type):
                                     raise SemanticError(f"Semantic Error: Type mismatch — cannot assign water({water_type}) to '{var_type}' list element.", water_line)
                                 value_node = ASTNode("Input", f"water({water_type})" if water_type else "water()", line=water_line)
@@ -698,20 +626,17 @@ def parse_statement(tokens, index, func_type = None):
                             
                         
                 elif tokens[index + 1].type == ".":
-                    # Bundle member assignment: p.age = 19; or p.addr.zip = 1000;
                     obj_name = tokens[index].value
                     member_name = tokens[index + 2].value
-                    # Validate bundle type and member
                     if var_type not in symbol_table.bundle_types:
                         raise SemanticError(f"Semantic Error: Variable '{obj_name}' is not a bundle type.", line)
                     bundle_members = symbol_table.bundle_types[var_type]
                     if member_name not in bundle_members:
                         raise SemanticError(f"Semantic Error: Bundle type '{var_type}' has no member '{member_name}'.", line)
                     member_type = bundle_members[member_name]
-                    index += 3  # skip id, '.', member
+                    index += 3
                     target = MemberAccessNode(obj_name, member_name, line=line)
 
-                    # Handle chained access for nested bundles: p.addr.zip
                     while tokens[index].type == "." and member_type in symbol_table.bundle_types:
                         next_member = tokens[index + 1].value
                         nested_members = symbol_table.bundle_types[member_type]
@@ -719,24 +644,23 @@ def parse_statement(tokens, index, func_type = None):
                             raise SemanticError(f"Semantic Error: Bundle type '{member_type}' has no member '{next_member}'.", line)
                         member_type = nested_members[next_member]
                         target = MemberAccessNode(target, next_member, line=line)
-                        index += 2  # skip '.', member
+                        index += 2
 
                     if tokens[index].type == "=":
-                        index += 1  # skip '='
-                        # Handle water() input for bundle members
+                        index += 1
                         if tokens[index].value == "water":
                             water_line = tokens[index].line
-                            index += 1  # skip 'water'
+                            index += 1
                             if tokens[index].type != "(":
                                 raise SemanticError(f"Syntax Error: Expected '(' after water.", water_line)
-                            index += 1  # skip '('
+                            index += 1
                             water_type = None
                             if tokens[index].value in {"seed", "tree", "leaf", "branch", "vine"}:
                                 water_type = tokens[index].value
                                 index += 1
                             if tokens[index].type != ")":
                                 raise SemanticError(f"Semantic Error: water() accepts only an optional type parameter (e.g., water(seed)).", water_line)
-                            index += 1  # skip ')'
+                            index += 1
                             if water_type and not _types_compatible(member_type, water_type):
                                 raise SemanticError(f"Semantic Error: Type mismatch — cannot assign water({water_type}) to '{member_type}' member '{member_name}'.", water_line)
                             value_node = ASTNode("Input", f"water({water_type})" if water_type else "water()", line=water_line)
@@ -745,22 +669,20 @@ def parse_statement(tokens, index, func_type = None):
                         assign_node = AssignmentNode(target, value_node, line=line)
                         assignments_node.add_child(assign_node)
                     elif tokens[index].type in {"+=", "-=", "*=", "/=", "%=", "**="}:
-                        # Compound assignment on bundle member: p.age += 1
                         if member_type not in {"seed", "tree"}:
                             raise SemanticError(f"Semantic Error: Compound assignment '{tokens[index].value}' is not valid for '{member_type}' member '{member_name}'.", line)
                         compound_op = tokens[index].value
                         base_op = compound_op[:-1]
-                        index += 1  # skip compound op
+                        index += 1
                         rhs_node, index = parse_expression_type(tokens, index, member_type)
                         value_node = BinaryOpNode(target, base_op, rhs_node, line=line)
                         assign_node = AssignmentNode(target, value_node, line=line)
                         assignments_node.add_child(assign_node)
                     elif tokens[index].type in {"++", "--"}:
-                        # Postfix increment/decrement on bundle member: p.age++;
                         if member_type not in {"seed", "tree"}:
                             raise SemanticError(f"Semantic Error: Cannot apply '{tokens[index].value}' to member '{member_name}' of type '{member_type}'.", line)
                         operator = tokens[index].value
-                        index += 1  # skip ++/--
+                        index += 1
                         assignments_node.add_child(UnaryOpNode(operator, target, "post", line=line))
                     else:
                         raise SemanticError(f"Semantic Error: Expected '=' after '{obj_name}.{member_name}'.", line)
@@ -789,9 +711,8 @@ def parse_statement(tokens, index, func_type = None):
                     assignments_node.add_child(UnaryOpNode(operator, operand, "post", line=line))
 
                 elif tokens[index + 1].type in {"+=", "-=", "*=", "/=", "%=", "**="}:
-                    # Compound assignment: x += 5  =>  x = x + 5
-                    compound_op = tokens[index + 1].value  # e.g. '+='
-                    base_op = compound_op[:-1]  # e.g. "+" from "+=", "**" from "**="
+                    compound_op = tokens[index + 1].value
+                    base_op = compound_op[:-1]
                     cur_var_name = tokens[index].value
                     cur_var_info = symbol_table.lookup_variable(cur_var_name)
                     if isinstance(cur_var_info, str):
@@ -801,15 +722,13 @@ def parse_statement(tokens, index, func_type = None):
                     cur_var_type = cur_var_info["type"]
                     if cur_var_type not in {"seed", "tree"}:
                         raise SemanticError(f"Semantic Error: Cannot use compound assignment on '{cur_var_name}' of type '{cur_var_type}'.", line)
-                    # ── modulo-assign guard: %= requires seed ──
                     if base_op == "%" and cur_var_type != "seed":
                         raise SemanticError(
                             f"Semantic Error: Modulo operator '%' requires 'seed' (integer) operands, "
                             f"but '{cur_var_name}' is of type 'tree'.",
                             line,
                         )
-                    # ──────────────────────────────────────────────
-                    index += 2  # skip id and compound op
+                    index += 2
                     rhs_node, index, rhs_type = parse_expression(tokens, index)
                     if rhs_type not in {"seed", "tree"}:
                         raise SemanticError(
@@ -834,15 +753,13 @@ def parse_statement(tokens, index, func_type = None):
                     if isinstance(var_info, str):
                         raise SemanticError(f"Semantic Error: Variable '{var_name}' used before declaration.", line)
 
-                    # ++arr[i]; — prefix on indexed array element
                     if tokens[index + 1].type == "[":
                         if var_info["type"] not in {"seed", "tree"}:
                             raise SemanticError(f"Semantic Error: Cannot use '{var_name}' of type {var_info['type']} in expression.", line)
                         list_access_node, index = parse_list_access(tokens, index)
-                        index += 1  # advance past the trailing ']'
+                        index += 1
                         assignments_node.add_child(UnaryOpNode(operator, list_access_node, "pre", line=line))
 
-                    # ++obj.field; — prefix on bundle member
                     elif tokens[index + 1].type == ".":
                         obj_name = tokens[index].value
                         if var_info["type"] not in symbol_table.bundle_types:
@@ -852,9 +769,8 @@ def parse_statement(tokens, index, func_type = None):
                         if member_name not in bundle_members:
                             raise SemanticError(f"Semantic Error: Bundle type '{var_info['type']}' has no member '{member_name}'.", line)
                         member_type = bundle_members[member_name]
-                        index += 3  # skip id, '.', member
+                        index += 3
                         target = MemberAccessNode(obj_name, member_name, line=line)
-                        # nested member access: ++p.addr.zip
                         while tokens[index].type == "." and member_type in symbol_table.bundle_types:
                             next_member = tokens[index + 1].value
                             nested_members = symbol_table.bundle_types[member_type]
@@ -867,7 +783,6 @@ def parse_statement(tokens, index, func_type = None):
                             raise SemanticError(f"Semantic Error: Cannot apply '{operator}' to member '{member_name}' of type '{member_type}'.", line)
                         assignments_node.add_child(UnaryOpNode(operator, target, "pre", line=line))
 
-                    # ++x; — prefix on plain identifier (original path)
                     else:
                         if var_info["type"] not in {"seed", "tree"}:
                             raise SemanticError(f"Semantic Error: Cannot use '{var_name}' of type {var_info['type']} in expression.", line)
@@ -943,14 +858,13 @@ def parse_statement(tokens, index, func_type = None):
         raise SemanticError(f"Semantic Error: '{token.value}' statement used outside a 'harvest' block.", line)
 
     elif token.type == "{":
-        # Bare block: { ... }
-        index += 1  # skip '{'
+        index += 1
         block_node = ASTNode("Block", line=line)
         while tokens[index].type != "}":
             stmt, index = parse_statement(tokens, index, func_type)
             if stmt:
                 block_node.add_child(stmt)
-        index += 1  # skip '}'
+        index += 1
         return block_node, index
 
     else:
@@ -973,7 +887,6 @@ def parse_list_access(tokens, index):
 
     index_node, index, idx_type = parse_equality(tokens, index)
 
-    # Array indices must be seed (integer)
     if idx_type is not None and idx_type != "seed":
         raise SemanticError(
             f"Semantic Error: List index must be of type 'seed', got '{idx_type}'.",
@@ -988,9 +901,8 @@ def parse_list_access(tokens, index):
 
     node = ListAccessNode(list_name, index_wrapper, line=line)
 
-    # Handle multi-dimensional access: m[1][2]
     while tokens[index + 1].type == "[":
-        index += 2  # skip ']' and '['
+        index += 2
         inner_index_node, index, inner_idx_type = parse_equality(tokens, index)
         if inner_idx_type is not None and inner_idx_type != "seed":
             raise SemanticError(
@@ -1007,7 +919,6 @@ def parse_list_access(tokens, index):
 
 
 def parse_list_assignment(tokens, index):
-    """Parses full list assignment, list operations, or function calls on a list."""
     line = tokens[index].line
     var_name = tokens[index].value
 
@@ -1025,7 +936,6 @@ def parse_list_assignment(tokens, index):
     if var_info.get("is_fertile", False):
         raise SemanticError(f"Semantic Error: Variable '{var_name}' is declared as fertile.", line)
 
-    # List functions
     if tokens[index].value == "append":
         value_node, index = parse_append(tokens, index, var_name, var_type)
 
@@ -1035,7 +945,6 @@ def parse_list_assignment(tokens, index):
     elif tokens[index].value == "remove":
         value_node, index = parse_remove(tokens, index, var_name, var_type)
 
-    # Assignment from another list
     elif tokens[index].type == "id":
         source_var = tokens[index].value
         source_info = symbol_table.lookup_variable(source_var)
@@ -1076,7 +985,6 @@ def parse_list_assignment(tokens, index):
             value_node = ASTNode("Value", source_var, line=line)
             index += 1
 
-    # Assignment from list literal
     elif tokens[index].type == "[":
         value_node, index = parse_list(tokens, index, var_type)
 
@@ -1087,13 +995,10 @@ def parse_list_assignment(tokens, index):
 
 
 def _types_compatible(declared, inferred):
-    """Check whether *inferred* expression type can be stored in a *declared* variable."""
     if declared == inferred:
         return True
-    # seed (int) and tree (float) are mutually compatible
     if declared in {"seed", "tree"} and inferred in {"seed", "tree"}:
         return True
-    # Bundle types are compatible if they are the same type (checked above)
     return False
 
 
@@ -1105,7 +1010,6 @@ def parse_expression_type(tokens, index, var_type):
 
     node, index, expr_type = parse_assignment_expression(tokens, index)
 
-    # --- type-mismatch guard ---
     if expr_type is None:
         raise SemanticError(
             "Semantic Error: Could not determine the type of the expression.",
@@ -1172,7 +1076,7 @@ def parse_expression_leaf(tokens, index):
         func_name = tokens[index].value
         func_info = symbol_table.lookup_function(func_name)
 
-        if isinstance(func_info, str):  # Function not found
+        if isinstance(func_info, str):
             raise SemanticError(f"Semantic Error: Function '{func_name}' is not defined.", line)
 
         func_return_type = func_info["return_type"]
@@ -1204,15 +1108,14 @@ def parse_expression_leaf(tokens, index):
         index += 1
         node = ListAccessNode(list_name, index_node, line=token.line)
 
-        # Handle multi-dimensional access: m[1][2]
         while index < len(tokens) and tokens[index].type == "[":
-            index += 1  # skip '['
+            index += 1
             inner_expr, index, _ = parse_expression(tokens, index)
             if tokens[index].type != "]":
                 raise SemanticError("Syntax Error: Missing closing bracket.", token.line)
             inner_index = ASTNode("Index", line=token.line)
             inner_index.add_child(inner_expr)
-            index += 1  # skip ']'
+            index += 1
             node = ListAccessNode(node, inner_index, line=token.line)
 
     elif tokens[index].type == "id":
@@ -1245,7 +1148,7 @@ def parse_expression_leaf(tokens, index):
                 func_name = tokens[index].value
                 func_info = symbol_table.lookup_function(func_name)
 
-                if isinstance(func_info, str):  # Function not found
+                if isinstance(func_info, str):
                     raise SemanticError(f"Semantic Error: Function '{func_name}' is not defined.", line)
 
                 func_return_type = func_info["return_type"]
@@ -1302,21 +1205,7 @@ def parse_expression_leaf(tokens, index):
     return left_node, index 
 
 
-# ============================================================================
-# EXPRESSION PARSER - Operator-precedence climbing
-# Standard precedence ladder built from these layered functions:
-#   parse_expression    : + - `      (lowest precedence)
-#   parse_term          : * / %
-#   parse_power         : **         (right-associative)
-#   parse_unary         : ~ ! ++ --
-#   parse_factor        : literals, identifiers, function calls,
-#                          parenthesized expressions     (highest)
-# Each layer calls the next-higher-precedence layer for its operands.
-# All return (ast_node, new_index, inferred_type).
-# ============================================================================
 def parse_expression(tokens, index):
-    """Parses an expression with +, -, and ` (string concat).
-    Returns (node, index, type_str)."""
     left_node, index, left_type = parse_term(tokens, index)
 
     while tokens[index].type in {"+", "-", "`"}:
@@ -1324,7 +1213,6 @@ def parse_expression(tokens, index):
         token = tokens[index]
 
         if op == "`":
-            # Backtick joins vines and leaves; the resulting string is a vine.
             if left_type not in {"vine", "leaf"}:
                 raise SemanticError(
                     f"Semantic Error: Cannot concatenate - left operand is of type '{left_type}', expected 'vine' or 'leaf'.",
@@ -1340,7 +1228,6 @@ def parse_expression(tokens, index):
             left_node = BinaryOpNode(left_node, op, right_node)
             left_type = "vine"
         else:
-            # + or -: both operands must be numeric (seed or tree)
             if left_type not in {"seed", "tree"}:
                 raise SemanticError(
                     f"Semantic Error: Cannot use '{op}' on type '{left_type}'. Expected 'seed' or 'tree'.",
@@ -1354,29 +1241,24 @@ def parse_expression(tokens, index):
                     token.line,
                 )
             left_node = BinaryOpNode(left_node, op, right_node)
-            # Promote to tree if either operand is tree
             if left_type == "tree" or right_type == "tree":
                 left_type = "tree"
 
     return left_node, index, left_type
 
 def parse_term(tokens, index):
-    """Parses multiplication, division, and modulus with type checking.
-    Returns (node, index, type_str)."""
     left_node, index, left_type = parse_power(tokens, index)
 
     while tokens[index].type in {"*", "/", "%"}:
         op = tokens[index].value
         token = tokens[index]
 
-        # Validate left operand is numeric
         if left_type not in {"seed", "tree"}:
             raise SemanticError(
                 f"Semantic Error: Cannot use '{op}' on type '{left_type}'. Expected 'seed' or 'tree'.",
                 token.line,
             )
 
-        # ── modulo type guard: % requires seed (integer) operands ──
         if op == "%":
             if left_type == "tree":
                 raise SemanticError(
@@ -1388,7 +1270,6 @@ def parse_term(tokens, index):
         index += 1
         right_node, index, right_type = parse_power(tokens, index)
 
-        # Validate right operand is numeric
         if right_type not in {"seed", "tree"}:
             raise SemanticError(
                 f"Semantic Error: Cannot use '{op}' on type '{right_type}'. Expected 'seed' or 'tree'.",
@@ -1410,15 +1291,12 @@ def parse_term(tokens, index):
                 pass
             
         left_node = BinaryOpNode(left_node, op, right_node)
-        # Promote to tree if either operand is tree
         if left_type == "tree" or right_type == "tree":
             left_type = "tree"
 
     return left_node, index, left_type
 
 def parse_power(tokens, index):
-    """Parses right-associative exponentiation (**).
-    Returns (node, index, type_str)."""
     left_node, index, left_type = parse_unary(tokens, index)
 
     if tokens[index].type == "**":
@@ -1447,7 +1325,6 @@ def parse_power(tokens, index):
     return left_node, index, left_type
 
 def parse_unary(tokens, index):
-    """Returns (node, index, type_str)."""
 
     if tokens[index].type in {"++", "--", "-", "~"}:
         op = tokens[index].value
@@ -1480,9 +1357,6 @@ def parse_unary(tokens, index):
     return node, index, factor_type
 
 def parse_cast(tokens, index):
-    """Parses explicit type casting: (type)expression.
-    Supports all GAL types: seed, tree, leaf, branch, vine.
-    Returns (node, index, type_str)."""
     token = tokens[index]
     cast_types = {"seed", "tree", "leaf", "branch", "vine"}
     if token.type == "(" and tokens[index + 1].value in cast_types:
@@ -1500,8 +1374,6 @@ def parse_cast(tokens, index):
 
 
 def parse_factor(tokens, index):
-    """Parses literals, identifiers, parenthesized expressions, and postfix operators.
-    Returns (node, index, type_str)."""
     token = tokens[index]
 
     if token.type == "(" and tokens[index + 1].value in {"seed", "tree", "leaf", "branch", "vine"}:
@@ -1521,7 +1393,6 @@ def parse_factor(tokens, index):
         index += 1
         return node, index, infer_literal_type(token.type)
 
-    # water() is an I/O statement, not an expression
     if token.value == "water":
         raise SemanticError(f"Semantic Error: water() is an I/O statement, not an expression. It cannot be used inside an expression.", token.line)
 
@@ -1582,7 +1453,6 @@ def parse_factor(tokens, index):
         tokens[index].type == "id" and
         tokens[index + 1].type == "."
     ):
-        # Bundle member access in expression: p.age, p.name
         obj_name = tokens[index].value
         member_name = tokens[index + 2].value
 
@@ -1599,10 +1469,9 @@ def parse_factor(tokens, index):
             raise SemanticError(f"Semantic Error: Bundle type '{var_type}' has no member '{member_name}'.", token.line)
 
         member_type = bundle_members[member_name]
-        index += 3  # skip id, '.', member
+        index += 3
         node = MemberAccessNode(obj_name, member_name, line=token.line)
 
-        # Handle chained access for nested bundles: p.addr.zip
         while index < len(tokens) and tokens[index].type == "." and member_type in symbol_table.bundle_types:
             next_member = tokens[index + 1].value
             nested_members = symbol_table.bundle_types[member_type]
@@ -1610,7 +1479,7 @@ def parse_factor(tokens, index):
                 raise SemanticError(f"Semantic Error: Bundle type '{member_type}' has no member '{next_member}'.", token.line)
             member_type = nested_members[next_member]
             node = MemberAccessNode(node, next_member, line=token.line)
-            index += 2  # skip '.', member
+            index += 2
 
         return node, index, member_type
 
@@ -1637,29 +1506,26 @@ def parse_factor(tokens, index):
         index += 1
         list_access_node = ListAccessNode(list_name, index_node, line=token.line)
 
-        # Handle multi-dimensional access: m[1][2]
         while index < len(tokens) and tokens[index].type == "[":
-            index += 1  # skip '['
+            index += 1
             inner_expr, index, _ = parse_expression(tokens, index)
             if tokens[index].type != "]":
                 raise SemanticError("Syntax Error: Missing closing bracket.", token.line)
             inner_index = ASTNode("Index", line=token.line)
             inner_index.add_child(inner_expr)
-            index += 1  # skip ']'
+            index += 1
             list_access_node = ListAccessNode(list_access_node, inner_index, line=token.line)
 
-        # Handle bundle array member access: p[0].x or p[0].addr.zip
         if index < len(tokens) and tokens[index].type == "." and list_info["type"] in symbol_table.bundle_types:
-            index += 1  # skip '.'
+            index += 1
             member_name = tokens[index].value
             bundle_members = symbol_table.bundle_types[list_info["type"]]
             if member_name not in bundle_members:
                 raise SemanticError(f"Semantic Error: Bundle type '{list_info['type']}' has no member '{member_name}'.", token.line)
             member_type = bundle_members[member_name]
-            index += 1  # skip member name
+            index += 1
             node = ArrayMemberAccessNode(list_access_node, member_name, line=token.line)
 
-            # Handle chained access for nested bundles: p[0].addr.zip
             while index < len(tokens) and tokens[index].type == "." and member_type in symbol_table.bundle_types:
                 next_member = tokens[index + 1].value
                 nested_members = symbol_table.bundle_types[member_type]
@@ -1667,7 +1533,7 @@ def parse_factor(tokens, index):
                     raise SemanticError(f"Semantic Error: Bundle type '{member_type}' has no member '{next_member}'.", token.line)
                 member_type = nested_members[next_member]
                 node = MemberAccessNode(node, next_member, line=token.line)
-                index += 2  # skip '.', member
+                index += 2
 
             return node, index, member_type
 
@@ -1704,7 +1570,6 @@ def parse_factor(tokens, index):
 
 
 def _assignment_root_name(node):
-    """Return the declared root variable of an assignable AST node."""
     if node.node_type in {"Identifier", "Value", "Object", "ListName"}:
         if isinstance(node.value, ASTNode):
             return _assignment_root_name(node.value)
@@ -1715,7 +1580,6 @@ def _assignment_root_name(node):
 
 
 def _assignment_target(node, line):
-    """Validate and normalize an assignment-expression left-hand side."""
     root_name = _assignment_root_name(node)
     valid_node_types = {"Value", "Identifier", "ListAccess", "MemberAccess", "ArrayMemberAccess"}
     var_info = symbol_table.lookup_variable(root_name) if root_name is not None else None
@@ -1737,7 +1601,6 @@ def _assignment_target(node, line):
 
 
 def parse_assignment_expression(tokens, index):
-    """Parse right-associative assignments and infer their stored value type."""
     line = tokens[index].line
     left_node, index, left_type = parse_logical_expression(tokens, index)
     if tokens[index].type not in {"=", "+=", "-=", "*=", "/=", "%="}:
@@ -1772,12 +1635,10 @@ def parse_assignment_expression(tokens, index):
 
 
 def parse_expression_branch(tokens, index):
-    """Parse the full expression form used by conditions and parentheses."""
     return parse_assignment_expression(tokens, index)
 
 
 def parse_logical_expression(tokens, index):
-    """Parses logical expressions with &&/|| operators for branch type."""
     line = tokens[index].line
     left_node, index, left_type = parse_equality(tokens, index)
 
@@ -1800,7 +1661,6 @@ def parse_logical_expression(tokens, index):
 
 
 def parse_equality(tokens, index):
-    """Parses equality expressions with == or !=."""
     line = tokens[index].line
     left_node, index, left_type = parse_relational(tokens, index)
 
@@ -1809,7 +1669,6 @@ def parse_equality(tokens, index):
         index += 1
         right_node, index, right_type = parse_relational(tokens, index)
 
-        # ── type guard: equality operators require compatible types ──
         if left_type is None or right_type is None:
             raise SemanticError(
                 "Semantic Error: Could not determine the type of an operand in equality check.",
@@ -1821,7 +1680,6 @@ def parse_equality(tokens, index):
                 f"Semantic Error: Cannot compare '{left_type}' with '{right_type}' using '{operator}'.",
                 line,
             )
-        # ──────────────────────────────────────────────────────────────
 
         left_node = BinaryOpNode(left_node, operator, right_node, line=line)
         left_type = "branch"
@@ -1830,7 +1688,6 @@ def parse_equality(tokens, index):
 
 
 def parse_relational(tokens, index):
-    """Parses relational expressions with <, >, <=, >= or ! unary operator."""
     line = tokens[index].line
 
     if tokens[index].type == "!":
@@ -1855,7 +1712,6 @@ def parse_relational(tokens, index):
                 line,
             )
 
-        # ── type guard: relational operators require compatible types ──
         if left_type and right_type:
             numeric = {"seed", "tree"}
             if left_type in numeric and right_type not in numeric:
@@ -1873,7 +1729,6 @@ def parse_relational(tokens, index):
                     f"Semantic Error: Cannot compare '{left_type}' with '{right_type}' using '{operator}'.",
                     line,
                 )
-        # ──────────────────────────────────────────────────────────────
 
         left_node = BinaryOpNode(left_node, operator, right_node, line=line)
         left_type = "branch"
@@ -1905,15 +1760,12 @@ def check_lwk(tokens, index):
     return op_found, start_index
 
 def parse_operand(tokens, index):
-    """Determines the parsing function based on the operand type."""
     token = tokens[index]
     line = token.line
 
-    # water() is an I/O statement, not an expression
     if token.value == "water":
         raise SemanticError(f"Semantic Error: water() is an I/O statement, not an expression. It cannot be used inside an expression.", token.line)
 
-    # Handle parentheses
     if token.type == "(":
         if tokens[index+1].value in {"seed", "tree"}:
             expr_type = tokens[index+1].value
@@ -1946,18 +1798,15 @@ def parse_operand(tokens, index):
         index += 1
         return expr_node, index, expr_type
 
-    # Chungus or Chudeluxe (arithmetic types)
     if token.type in {"intlit", "dbllit"}:
         expr_node, index, _ = parse_expression(tokens, index)
         return expr_node, index, infer_literal_type(token.type)
 
-    # Forsencd (String concatenation or manipulation)
     if token.type in {"chrlit", "stringlit"}:
         expr_node, index, _ = parse_expression(tokens, index)
         return expr_node, index, infer_literal_type(token.type)
 
 
-    # Lwk (Boolean literal)
     if token.type in {"sunshine", "frost"}:
         expr_node, index, _ = parse_expression(tokens, index)
         return expr_node, index, infer_literal_type(token.type)
@@ -1985,36 +1834,29 @@ def parse_operand(tokens, index):
         if not list_info["is_list"] and list_info.get("type") != "vine":
             raise SemanticError(f"Semantic Error: '{list_name}' is not a list.", token.line)
 
-        # Delegate to parse_expression so arithmetic (a[0] + a[1]) is handled
         expr_node, index, expr_type = parse_expression(tokens, index)
         return expr_node, index, expr_type
 
-    # Chungus or Chudeluxe (arithmetic types)
     if token.type in {"intlit", "dbllit"}:
         expr_node, index, _ = parse_expression(tokens, index)
         return expr_node, index, infer_literal_type(token.type)
 
-    # Forsencd (String concatenation or manipulation)
     if token.type == "chrlit":
         expr_node, index = parse_expression_leaf(tokens, index)
         return expr_node, index, infer_literal_type(token.type)
 
-    # Forsen (String literal)
     if token.type == "stringlit":
         return ASTNode("Value", token.value, line=line), index + 1, "vine"
 
-    # Lwk (Boolean literal)
     if token.type in {"sunshine", "frost"}:
         return ASTNode("Value", token.value, line=line), index + 1, "branch"
 
-    # Bundle member access in operand context: p.age > 18 or p.addr.zip > 0
     if token.type == "id" and tokens[index + 1].type == ".":
         var_info = symbol_table.lookup_variable(token.value)
         if not isinstance(var_info, str) and var_info["type"] in symbol_table.bundle_types:
             expr_node, index, expr_type = parse_expression(tokens, index)
             return expr_node, index, expr_type
 
-    # Identifiers (Variables)
     if token.type == "id":
         var_info = symbol_table.lookup_variable(token.value)
         if isinstance(var_info, str):
@@ -2024,7 +1866,6 @@ def parse_operand(tokens, index):
         is_list = var_info.get("is_list", False)
 
         if is_list and tokens[index + 1].type != "[":
-            # Check if this is an array <op> array case (e.g., x = a + b)
             if tokens[index + 1].type in {"+", "-", "*", "/", "%", "**", "==", "!=", ">", "<", ">=", "<="}:
                 op_token = tokens[index + 1]
                 if index + 2 < len(tokens) and tokens[index + 2].type == "id":
@@ -2036,7 +1877,6 @@ def parse_operand(tokens, index):
                         )
             raise SemanticError(f"Semantic Error: List '{token.value}' must be indexed with '[]' in expressions.", line)
     
-        # Dispatch to specific parsers based on type
         if var_type in {"seed", "tree", "branch"}:
             expr_node, index, _ = parse_expression(tokens, index)
             
@@ -2054,7 +1894,6 @@ def parse_operand(tokens, index):
             return ASTNode("Value", token.value, line=line), index + 1, var_type
 
         elif var_type in symbol_table.bundle_types:
-            # Bundle variable used directly — dispatch through expression parser
             expr_node, index, _ = parse_expression(tokens, index)
             return expr_node, index, var_type
 
@@ -2067,7 +1906,6 @@ def parse_operand(tokens, index):
 
 
 def infer_literal_type(token_type):
-    """Returns the type string for a given literal token type."""
     if token_type == "intlit":
         return "seed"
     if token_type == "dbllit":
@@ -2089,17 +1927,17 @@ def parse_assignment(tokens, index, var_name, var_type):
 
     if tokens[index].value == "water":
         water_line = tokens[index].line
-        index += 1  # skip 'water'
+        index += 1
         if tokens[index].type != "(":
             raise SemanticError(f"Syntax Error: Expected '(' after water.", water_line)
-        index += 1  # skip '('
+        index += 1
         water_type = None
         if tokens[index].value in {"seed", "tree", "leaf", "branch", "vine"}:
             water_type = tokens[index].value
             index += 1
         if tokens[index].type != ")":
             raise SemanticError(f"Semantic Error: water() accepts only an optional type parameter (e.g., water(seed)).", water_line)
-        index += 1  # skip ')'
+        index += 1
         if water_type and not _types_compatible(var_type, water_type):
             raise SemanticError(f"Semantic Error: Type mismatch — cannot assign water({water_type}) to '{var_type}' variable.", water_line)
         value_node = ASTNode("Input", f"water({water_type})" if water_type else "water()", line=water_line)
@@ -2125,12 +1963,10 @@ def parse_function_call(tokens, index, func_name, func_type, func_params):
 
         expected_type = expected_params[len(provided_args)].children[0].value 
         
-        # Check if the expected parameter is an array parameter
         expected_param = expected_params[len(provided_args)]
         is_array_param = any(child.node_type == "ArrayParam" for child in expected_param.children)
 
         if is_array_param:
-            # Array parameter: expect an array identifier
             if tokens[index].type != "id":
                 raise SemanticError(f"Semantic Error: Expected array variable for parameter {len(provided_args) + 1} of '{func_name}'.", line)
             arg_name = tokens[index].value
@@ -2165,7 +2001,7 @@ def parse_function_call(tokens, index, func_name, func_type, func_params):
         raise SemanticError(f"Semantic Error: Function '{func_name}' expects {len(expected_params)} arguments, but {len(provided_args)} were provided.", line)
 
     for i, (arg_node, arg_type) in enumerate(provided_args):
-        expected_type = expected_params[i].children[0].value  # Get expected type
+        expected_type = expected_params[i].children[0].value
 
         if expected_type in {"seed", "tree"} and arg_type == "seed":
             continue 
@@ -2177,39 +2013,34 @@ def parse_function_call(tokens, index, func_name, func_type, func_params):
 
 
 def parse_water_statement(tokens, index):
-    """Parse water(variable); — reads input into an existing variable."""
     line = tokens[index].line
-    index += 1  # skip 'water'
+    index += 1
 
     if tokens[index].type != "(":
         raise SemanticError(f"Syntax Error: Expected '(' after water.", line)
-    index += 1  # skip '('
+    index += 1
 
-    # Case 1: water() or water(data_type) — no variable target (expression form used as statement)
     if tokens[index].value in {"seed", "tree", "leaf", "branch", "vine"}:
         water_type = tokens[index].value
         index += 1
         if tokens[index].type != ")":
             raise SemanticError(f"Semantic Error: water() accepts only an optional type parameter or a variable name.", line)
-        index += 1  # skip ')'
+        index += 1
         if tokens[index].type != ";":
             raise SemanticError(f"Syntax Error: Expected ';' after water statement.", line)
-        index += 1  # skip ';'
-        # Standalone typed water with no target — just returns input (discarded)
+        index += 1
         input_node = ASTNode("Input", f"water({water_type})", line=line)
         return input_node, index
 
     elif tokens[index].type == ")":
-        # water() with no args
-        index += 1  # skip ')'
+        index += 1
         if tokens[index].type != ";":
             raise SemanticError(f"Syntax Error: Expected ';' after water statement.", line)
-        index += 1  # skip ';'
+        index += 1
         input_node = ASTNode("Input", "water()", line=line)
         return input_node, index
 
     elif tokens[index].type == "id":
-        # water(variable) — read input into variable
         var_name = tokens[index].value
         var_info = symbol_table.lookup_variable(var_name)
         if isinstance(var_info, str):
@@ -2217,56 +2048,52 @@ def parse_water_statement(tokens, index):
         if var_info.get("is_fertile", False):
             raise SemanticError(f"Semantic Error: Variable '{var_name}' is declared as fertile and cannot be re-assigned a value.", line)
         var_type = var_info["type"]
-        index += 1  # skip identifier
+        index += 1
 
-        # Check for list element access: water(arr[i])
         if tokens[index].type == "[":
             if not var_info.get("is_list", False) and var_info.get("type") != "vine":
                 raise SemanticError(f"Semantic Error: Variable '{var_name}' is not a list.", line)
-            index += 1  # skip '['
+            index += 1
             index_expr, index, idx_type = parse_equality(tokens, index)
             if idx_type is not None and idx_type != "seed":
                 raise SemanticError(f"Semantic Error: List index must be of type 'seed', got '{idx_type}'.", line)
             if tokens[index].type != "]":
                 raise SemanticError(f"Syntax Error: Expected ']' after list index.", line)
-            index += 1  # skip ']'
+            index += 1
 
-            # Build first dimension: arr[i]
             index_wrapper = ASTNode("Index", line=line)
             index_wrapper.add_child(index_expr)
             list_access_node = ListAccessNode(var_name, index_wrapper, line=line)
 
-            # Handle additional dimensions: water(arr[i][j][k]...)
             while tokens[index].type == "[":
-                index += 1  # skip '['
+                index += 1
                 inner_expr, index, inner_type = parse_equality(tokens, index)
                 if inner_type is not None and inner_type != "seed":
                     raise SemanticError(f"Semantic Error: List index must be of type 'seed', got '{inner_type}'.", line)
                 if tokens[index].type != "]":
                     raise SemanticError(f"Syntax Error: Expected ']' after list index.", line)
-                index += 1  # skip ']'
+                index += 1
                 inner_wrapper = ASTNode("Index", line=line)
                 inner_wrapper.add_child(inner_expr)
                 list_access_node = ListAccessNode(list_access_node, inner_wrapper, line=line)
 
             if tokens[index].type != ")":
                 raise SemanticError(f"Semantic Error: Expected ')' after water(arr[i]).", line)
-            index += 1  # skip ')'
+            index += 1
             if tokens[index].type != ";":
                 raise SemanticError(f"Syntax Error: Expected ';' after water statement.", line)
-            index += 1  # skip ';'
+            index += 1
             input_node = ASTNode("Input", f"water({var_type})", line=line)
             assignment_node = AssignmentNode(list_access_node, input_node, line=line)
             return assignment_node, index
 
         if tokens[index].type != ")":
             raise SemanticError(f"Semantic Error: water() accepts only a single variable name or type parameter.", line)
-        index += 1  # skip ')'
+        index += 1
         if tokens[index].type != ";":
             raise SemanticError(f"Syntax Error: Expected ';' after water statement.", line)
-        index += 1  # skip ';'
+        index += 1
 
-        # Build as: variable = water(type)  — an assignment with Input as the value
         input_node = ASTNode("Input", f"water({var_type})", line=line)
         value_ident = ASTNode("Identifier", var_name, line=line)
         assignment_node = AssignmentNode(var_name, input_node, line=line)
@@ -2356,7 +2183,6 @@ def parse_print(tokens, index):
                 raise SemanticError(f"Semantic Error: Variable '{identif_name}' used before declaration.", line)
             
             if tokens[index + 1].type == "." and arg_info["type"] in symbol_table.bundle_types:
-                # Bundle member access in plant: plant(p.name)
                 expr_node, index, _ = parse_expression(tokens, index)
                 args.append(expr_node)
 
@@ -2468,7 +2294,6 @@ def parse_print(tokens, index):
                     raise SemanticError(f"Semantic Error: List '{arg_name}' must be indexed with '[]' in expressions.", line)
                 
             if tokens[index + 1].type == "." and arg_info["type"] in symbol_table.bundle_types:
-                # Bundle member access in plant args: plant("{}", p.name)
                 arg_node, index, _ = parse_expression(tokens, index)
                 actual_args.append(arg_node)
 
@@ -2510,7 +2335,6 @@ def parse_print(tokens, index):
     if placeholder_count > 15:
         raise SemanticError(f"Semantic Error: Exceeded maximum amount of 15 arguments in plant statement.", line)
 
-    # Only enforce placeholder matching when the format string contains {}
     if placeholder_count > 0 and placeholder_count != len(actual_args):
         raise SemanticError(f"Semantic Error: Found {len(actual_args)} argument(s). Expected {placeholder_count} argument(s).", line)
     
@@ -2623,21 +2447,15 @@ def parse_fertile(tokens, index):
 
     return FertileDeclarationNode(var_type, var_name, value_node, line=line), index
 
-# ============================================================================
-# CONTROL-FLOW PARSERS - parse_if / parse_for / parse_while / parse_do /
-# parse_switch. Each builds the matching AST node (IfStatementNode,
-# ForLoopNode, etc.) and recursively parses the body via parse_statement.
-# Conditions must evaluate to a branch (boolean) — checked here.
-# ============================================================================
 def parse_if(tokens, index, func_type):
     line = tokens[index].line
-    index += 1  # Move past "spring"
+    index += 1
 
     if tokens[index].type != "(":
         raise SemanticError(f"Syntax Error: Expected '(' after 'spring'.", line)
     index += 1
 
-    condition_expr, index, cond_type = parse_expression_branch(tokens, index)  # Parse branch expression
+    condition_expr, index, cond_type = parse_expression_branch(tokens, index)
 
     if cond_type != "branch":
         raise SemanticError(f"Semantic Error: spring condition must be branch, got {cond_type}.", line)
@@ -2674,7 +2492,6 @@ def parse_if(tokens, index, func_type):
         raise SemanticError(f"Syntax Error: Expected '{{' after 'spring' condition.", line)
 
 
-    # Else-if chains: bud (<cond>) { ... }
     while tokens[index].value == "bud":
         index += 1
 
@@ -2719,7 +2536,6 @@ def parse_if(tokens, index, func_type):
             raise SemanticError(f"Syntax Error: Expected '{{' after else-if condition.", line)
 
 
-    # Else: wither { ... }
     if tokens[index].value == "wither":
         index += 1
 
@@ -2757,10 +2573,10 @@ def parse_return(tokens, index, func_type):
     elif tokens[index].type == "id":
         identifier = tokens[index].value
 
-        if tokens[index+1].type == "(":  # Function call case
+        if tokens[index+1].type == "(":
             func_info = symbol_table.lookup_function(identifier)
 
-            if isinstance(func_info, str):  # Function not found
+            if isinstance(func_info, str):
                 raise SemanticError(f"Semantic Error: Function '{identifier}' is not defined.", line)
 
             return_type = func_info["return_type"]
@@ -2769,13 +2585,11 @@ def parse_return(tokens, index, func_type):
 
             return_expr, index = parse_expression_type(tokens, index, func_type)
 
-        else:  # Variable case
+        else:
             var_info = symbol_table.lookup_variable(identifier)
             if isinstance(var_info, str):
                 raise SemanticError(f"Semantic Error: Variable '{identifier}' used before declaration.", line)
 
-            # Skip preliminary type check when the variable is a bundle with member access (e.g., p.a)
-            # because the expression type depends on the member, not the base variable
             is_member_access = var_info["type"] in symbol_table.bundle_types and tokens[index+1].type == "."
             if not is_member_access:
                 if var_info["type"] not in [func_type, "seed", "tree"] and var_info["type"] != "seed" and var_info["type"] != "tree":                
@@ -2789,7 +2603,6 @@ def parse_return(tokens, index, func_type):
     return ReturnNode(return_expr, line=line), index
 
 
-
 def parse_for(tokens, index, func_type):
     line = tokens[index].line
     index += 1
@@ -2910,11 +2723,10 @@ def parse_update(tokens, index):
                             assign_node = AssignmentNode(list_access_node, value_node, line=tokens[index].line)
                             assignments_node.add_child(assign_node)
                         elif tokens[index + 1].type in {"++", "--"}:
-                            # arr[i]++ in for-update (cultivate(...; ...; arr[i]++))
                             if var_type not in {"seed", "tree"}:
                                 raise SemanticError(f"Semantic Error: Cannot use '{var_name}' of type {var_type} in expression.", line)
                             operator = tokens[index + 1].value
-                            index += 2  # past ']' and ++/--
+                            index += 2
                             assignments_node.add_child(UnaryOpNode(operator, list_access_node, "post", line=line))
                         else:
                             raise SemanticError("Semantic Error: Expected '=' or '++'/'--' after list access.", tokens[index + 1].line)
@@ -2945,7 +2757,6 @@ def parse_update(tokens, index):
                     assignments_node.add_child(node)
 
                 elif tokens[index + 1].type in {"+=", "-=", "*=", "/=", "%=", "**="}:
-                    # Compound assignment in for-loop update: i += 2
                     compound_op = tokens[index + 1].value
                     base_op = compound_op[:-1]
                     cur_var_name = tokens[index].value
@@ -2957,15 +2768,13 @@ def parse_update(tokens, index):
                     cur_var_type = cur_var_info["type"]
                     if cur_var_type not in {"seed", "tree"}:
                         raise SemanticError(f"Semantic Error: Cannot use compound assignment on '{cur_var_name}' of type '{cur_var_type}'.", line)
-                    # ── modulo-assign guard: %= requires seed ──
                     if base_op == "%" and cur_var_type != "seed":
                         raise SemanticError(
                             f"Semantic Error: Modulo operator '%' requires 'seed' (integer) operands, "
                             f"but '{cur_var_name}' is of type 'tree'.",
                             line,
                         )
-                    # ──────────────────────────────────────────────
-                    index += 2  # skip id and compound op
+                    index += 2
                     rhs_node, index, rhs_type = parse_expression(tokens, index)
                     if rhs_type not in {"seed", "tree"}:
                         raise SemanticError(
@@ -2990,15 +2799,13 @@ def parse_update(tokens, index):
                     if isinstance(var_info, str):
                         raise SemanticError(f"Semantic Error: Variable '{var_name}' used before declaration.", line)
 
-                    # ++arr[i]; — prefix on indexed array element
                     if tokens[index + 1].type == "[":
                         if var_info["type"] not in {"seed", "tree"}:
                             raise SemanticError(f"Semantic Error: Cannot use '{var_name}' of type {var_info['type']} in expression.", line)
                         list_access_node, index = parse_list_access(tokens, index)
-                        index += 1  # advance past the trailing ']'
+                        index += 1
                         assignments_node.add_child(UnaryOpNode(operator, list_access_node, "pre", line=line))
 
-                    # ++obj.field; — prefix on bundle member
                     elif tokens[index + 1].type == ".":
                         obj_name = tokens[index].value
                         if var_info["type"] not in symbol_table.bundle_types:
@@ -3008,9 +2815,8 @@ def parse_update(tokens, index):
                         if member_name not in bundle_members:
                             raise SemanticError(f"Semantic Error: Bundle type '{var_info['type']}' has no member '{member_name}'.", line)
                         member_type = bundle_members[member_name]
-                        index += 3  # skip id, '.', member
+                        index += 3
                         target = MemberAccessNode(obj_name, member_name, line=line)
-                        # nested member access: ++p.addr.zip
                         while tokens[index].type == "." and member_type in symbol_table.bundle_types:
                             next_member = tokens[index + 1].value
                             nested_members = symbol_table.bundle_types[member_type]
@@ -3023,7 +2829,6 @@ def parse_update(tokens, index):
                             raise SemanticError(f"Semantic Error: Cannot apply '{operator}' to member '{member_name}' of type '{member_type}'.", line)
                         assignments_node.add_child(UnaryOpNode(operator, target, "pre", line=line))
 
-                    # ++x; — prefix on plain identifier (original path)
                     else:
                         if var_info["type"] not in {"seed", "tree"}:
                             raise SemanticError(f"Semantic Error: Cannot use '{var_name}' of type {var_info['type']} in expression.", line)
@@ -3173,7 +2978,7 @@ def parse_switch(tokens, index, func_type):
         raise SemanticError(f"Syntax Error: Expected '(' after 'harvest'.", line)
     index += 1
 
-    switch_type = None  # track the type of the harvest expression
+    switch_type = None
 
     if tokens[index].type == "id":
         var_info = symbol_table.lookup_variable(tokens[index].value)
@@ -3187,7 +2992,6 @@ def parse_switch(tokens, index, func_type):
         
 
     elif tokens[index].type in {"intlit", "chrlit", "sunshine", "frost"} or tokens[index].type in {"--", "++", "-", "("}:
-        # infer type from the leading token
         if tokens[index].type == "intlit" or tokens[index].type in {"--", "++", "-"}:
             switch_type = "seed"
         elif tokens[index].type == "chrlit":
@@ -3195,7 +2999,7 @@ def parse_switch(tokens, index, func_type):
         elif tokens[index].type in {"sunshine", "frost"}:
             switch_type = "branch"
         elif tokens[index].type == "(":
-            switch_type = "seed"  # default for grouped expressions
+            switch_type = "seed"
         switch_expr, index, _ = parse_expression(tokens, index)
 
     elif tokens[index].type in {"stringlit"}:
@@ -3219,7 +3023,7 @@ def parse_switch(tokens, index, func_type):
 
     case_nodes = []
     default_case = None
-    seen_case_values = set()  # track variety values to detect duplicates
+    seen_case_values = set()
 
     while tokens[index].value in {"variety"}:
         case_line = tokens[index].line
@@ -3229,7 +3033,6 @@ def parse_switch(tokens, index, func_type):
         if tokens[index].type not in {"chrlit", "stringlit", "sunshine", "frost", "intlit", "dbllit"}:
             raise SemanticError(f"Semantic Error: Expected valid literal value after 'variety'.", line)
 
-        # --- type-check the variety literal against the harvest expression ---
         lit_type_map = {
             "intlit": "seed",
             "dbllit": "tree",
@@ -3245,7 +3048,6 @@ def parse_switch(tokens, index, func_type):
                 tokens[index].line,
             )
 
-        # --- check for duplicate variety values ---
         case_val_key = tokens[index].value
         if case_val_key in seen_case_values:
             raise SemanticError(
@@ -3382,7 +3184,6 @@ def parse_insert(tokens, index, var_name, expected_type):
     index += 1
 
     expr_node, index, idx_type = parse_equality(tokens, index)
-    # Insert index must be seed (integer)
     if idx_type is not None and idx_type != "seed":
         raise SemanticError(
             f"Semantic Error: List index must be of type 'seed', got '{idx_type}'.",
@@ -3422,7 +3223,6 @@ def parse_remove(tokens, index, var_name, expected_type):
     index += 1
 
     expr_node, index, idx_type = parse_equality(tokens, index)
-    # Remove index must be seed (integer)
     if idx_type is not None and idx_type != "seed":
         raise SemanticError(
             f"Semantic Error: List index must be of type 'seed', got '{idx_type}'.",
@@ -3442,17 +3242,7 @@ def is_inside_loop_or_switch_stack():
     return any(ctx in {"WhileNode", "DoWhileNode", "SwitchNode", "ForNode"} for ctx in context_stack)
 
 
-# ============================================================================
-# analyze_semantics() - LEGACY ONE-SHOT ENTRY POINT
-# Older API that does build_ast in one call. The current pipeline uses
-# the two-step parse_and_build + validate_ast instead so the IDE can
-# distinguish 'syntax' from 'semantic' error stages.
-# ============================================================================
 def analyze_semantics(tokens):
-    """
-    Legacy API — builds AST from tokens and validates in one pass.
-    Kept for backward compatibility.
-    """
     try:
         filtered = [t for t in tokens if t.type != '\n']
         ast = build_ast(filtered)
@@ -3501,15 +3291,3 @@ def analyze_semantics(tokens):
         }
 
 
-# ============================================================================
-# SEMANTIC VALIDATION — Tree-Walking Pass
-# ============================================================================
-# After the parser builds the AST, this validator walks the tree to verify
-# semantic correctness.  The compiler pipeline is:
-#
-#   Lexer → Parser (LL1 + AST build) → Semantic (validate AST) → Interpreter
-#
-# The parser already performs primary checks during AST construction (variable
-# declarations, type dispatch, scope tracking).  This tree-walking pass serves
-# as the dedicated semantic analysis phase that validates the completed AST.
-# ============================================================================

Backend/parser/parser.py

@@ -1,23 +1,8 @@
-# ============================================================================
-# LL(1) PARSER - Table-driven syntax analysis
-# ============================================================================
-# Extracted from Backend/Gal_Parser.py during the modular restructure.
-# Pipeline position:
-#   lex -> THIS FILE (parse + delegate to builder) -> semantic -> ICG -> interpret
-#
-# The parser exposes two entry points:
-#   parse(tokens)            : syntax-only check, returns (success, errors)
-#   parse_and_build(tokens)  : syntax + AST construction (delegates to
-#                              parser.builder.build_ast)
-# ============================================================================
 from __future__ import annotations
 
 from dataclasses import dataclass
 from typing import Any, Dict, Iterable, List, Mapping, Optional, Sequence, Set, Tuple
 
-# AST builder imports — the parser builds the AST after LL(1) validation.
-# After the restructure, build_ast lives in parser/builder.py (a sibling),
-# not in GALsemantic.py.
 from .builder import (
     build_ast as _build_ast,
     symbol_table as _builder_st,
@@ -25,14 +10,8 @@ from .builder import (
 from semantic.errors import SemanticError as _SemanticError
 
 
-# ============================================================================
-# TOKEN VIEW HELPERS - The parser accepts tokens as either Token objects
-# or dicts (e.g. when reloaded from JSON). _TokView gives a uniform shape
-# so the parsing loop doesn't have to handle both cases.
-# ============================================================================
 @dataclass(frozen=True)
 class _TokView:
-    """Lightweight view to normalize token access."""
     type: str
     value: str
     line: int
@@ -40,16 +19,13 @@ class _TokView:
 
 
 def _as_tok(token: Any) -> _TokView:
-    """Normalize token objects/dicts to a common view."""
     if isinstance(token, Mapping):
-        # Dict-shaped token (came from a JSON request body)
         return _TokView(
             type=str(token.get("type", "")),
             value=str(token.get("value", "")),
             line=int(token.get("line", 0) or 0),
             col=int(token.get("col", 0) or 0),
         )
-    # Token object (the lexer's normal output)
     return _TokView(
         type=str(getattr(token, "type", "")),
         value=str(getattr(token, "value", "")),
@@ -58,9 +34,6 @@ def _as_tok(token: Any) -> _TokView:
     )
 
 
-# ============================================================================
-# LL1Parser - The table-driven LL(1) parser
-# ============================================================================
 class LL1Parser:
     def __init__(
         self,
@@ -78,32 +51,19 @@ class LL1Parser:
         self.predict_sets = predict_sets
         self.first_sets = first_sets
 
-        # GAL uses λ to denote the empty production in its CFG/FIRST/FOLLOW/PREDICT sets.
         self.epsilon_symbols: Set[str] = set(epsilon_symbols)
         self.start_symbol = start_symbol
         self.end_marker = end_marker
 
-        # If lexer emits newlines as tokens, treat them as skippable by default.
-        # The lexer uses '\n' as the token type for newlines
         self.skip_token_types: Set[str] = set(skip_token_types or {"\n"})
         self.token_type_alias = token_type_alias or {
-            # Helpful defaults based on inconsistencies seen in the document's token labels
-            # (e.g., 'idf' vs 'id', 'dbllit' vs 'dblit').
             'idf': 'id',
             'dbllit': 'dblit',
         }
         
         self.parsing_table: Dict[str, Dict[str, List[str]]] = self.construct_parsing_table()
 
-    # ========================================================================
-    # PARSING TABLE CONSTRUCTION
-    # Builds the LL(1) parsing table from the CFG + PREDICT sets.
-    # Layout: table[non_terminal][lookahead_token] = production_to_apply.
-    # Raises ValueError if the grammar isn't LL(1) (two productions claim
-    # the same lookahead) — this is the compile-time correctness check.
-    # ========================================================================
     def construct_parsing_table(self) -> Dict[str, Dict[str, List[str]]]:
-        """Build LL(1) parsing table using provided PREDICT sets."""
         table: Dict[str, Dict[str, List[str]]] = {}
 
         for non_terminal, productions in self.cfg.items():
@@ -112,8 +72,6 @@ class LL1Parser:
                 key = (non_terminal, tuple(production))
                 terms = self.predict_sets.get(key, set())
                 for terminal in terms:
-                    # An LL(1) conflict means the grammar can't be parsed
-                    # with one token of lookahead — fix the grammar first.
                     if terminal in row and row[terminal] != production:
                         raise ValueError(
                             f"LL(1) conflict at {non_terminal} with lookahead {terminal}: "
@@ -124,14 +82,7 @@ class LL1Parser:
         return table
 
 
-    # ========================================================================
-    # TOKEN NORMALIZATION HELPERS - Bridge between lexer and grammar
-    # The lexer emits some token types that don't match the CFG terminal
-    # names (e.g. 'dbllit' from lexer vs 'dblit' in cfg.py). The alias map
-    # papers over those differences in one place.
-    # ========================================================================
     def _normalize_token_type(self, token_type: str) -> str:
-        """Map lexer token types into the terminal names used by the CFG."""
         return self.token_type_alias.get(token_type, token_type)
 
     def _ensure_eof(self, toks: List[_TokView]) -> List[_TokView]:
@@ -143,17 +94,13 @@ class LL1Parser:
             toks = toks + [_TokView(self.end_marker, self.end_marker, last_line, last_col)]
         return toks
 
-    # ── human-readable names for terminals ──────────────────────────
     _TERMINAL_DISPLAY: Dict[str, str] = {
-        # literals / identifiers
         'id': 'id', 'intlit': 'intlit', 'dblit': 'dblit',
         'stringlit': 'stringlit', 'chrlit': 'chrlit',
         'sunshine': "'sunshine'", 'frost': "'frost'",
-        # data types
         'seed': "'seed'", 'tree': "'tree'",
         'leaf': "'leaf'", 'branch': "'branch'",
         'vine': "'vine'",
-        # keywords
         'bundle': "'bundle'", 'fertile': "'fertile'",
         'pollinate': "'pollinate'", 'root': "'root'",
         'reclaim': "'reclaim'", 'spring': "'spring'",
@@ -164,52 +111,31 @@ class LL1Parser:
         'prune': "'prune'", 'skip': "'skip'",
         'water': "'water'", 'plant': "'plant'",
         'empty': "'empty'",
-        # special
         'EOF': 'end of file',
     }
 
-    # ========================================================================
-    # ERROR-MESSAGE HELPERS
-    # When the parser hits a token that doesn't match any production, we
-    # build a friendly "Expected: X, Y, Z" string from the parsing-table
-    # row. _generate_helpful_error adds context-aware hints (e.g. "did you
-    # mean '==' instead of '='?").
-    # ========================================================================
     def _format_expected(self, expected: Set[str], non_terminal: Optional[str] = None) -> str:
-        """Return a human-readable string listing the expected terminals.
-
-        The *expected* set comes directly from the parsing-table row for
-        *non_terminal*, which is itself built from the PREDICT sets.
-        """
         symbols = {'(', ')', '{', '}', ';', ',', '=', '+', '-', '*', '/', '%',
                    '++', '--', '==', '!=', '<', '>', '<=', '>=', '&&', '||',
                    '!', '~', '+=', '-=', '*=', '/=', '%=', '.', '[', ']', ':', '`'}
-        # Only hide 'reclaim' from suggestions when the source already contains one
         has_reclaim = any(tk.type == 'reclaim' for tk in getattr(self, '_current_tokens', []))
 
         parts: List[str] = []
         for t in sorted(expected):
             if t == 'reclaim' and has_reclaim:
-                continue  # reclaim already present in source; omit from suggestions
+                continue
             if t in self._TERMINAL_DISPLAY:
                 parts.append(self._TERMINAL_DISPLAY[t])
             elif t in symbols:
                 parts.append(f"'{t}'")
             elif t.startswith('<') and t.endswith('>'):
-                continue  # skip non-terminal names
+                continue
             else:
                 parts.append(f"'{t}'")
         if not parts:
             return 'nothing'
         return f"Expected: {', '.join(parts)}"
 
-    # ========================================================================
-    # _GENERATE_HELPFUL_ERROR - The big one
-    # When a token doesn't match, this method inspects context (previous
-    # tokens, the non-terminal we're inside, common typos like '==='/' &&&')
-    # and produces a SPECIFIC error rather than a generic "Expected: ..."
-    # message. This is what makes GAL's error messages friendly.
-    # ========================================================================
     def _generate_helpful_error(
         self,
         non_terminal: str,
@@ -221,18 +147,14 @@ class LL1Parser:
         index: int,
         toks: List[_TokView]
     ) -> str:
-        """Generate contextual error messages for common syntax mistakes."""
         
-        # Parameter type keywords (used in multiple checks below)
         param_type_tokens = {'seed', 'tree', 'leaf', 'vine', 'branch'}
         
-        # PRIORITY CHECK: Unexpected end of file (missing closing brace)
         if token_type == self.end_marker or token_value == '':
             if '}' in expected:
                 return f"SYNTAX error line {line} col {col} Unexpected end of file. Missing closing '}}'. {self._format_expected(expected, non_terminal)}"
             return f"SYNTAX error line {line} col {col} Unexpected end of file. {self._format_expected(expected, non_terminal)}"
         
-        # PRIORITY CHECK: Detect === operator (tokenized as == followed by =)
         if token_type == '=' and index > 0:
             prev_index = index - 1
             while prev_index >= 0 and toks[prev_index].type in self.skip_token_types:
@@ -241,7 +163,6 @@ class LL1Parser:
             if prev_index >= 0 and toks[prev_index].type == '==':
                 return f"SYNTAX error line {line} col {col} Invalid operator '==='. Use '==' for equality comparison. {self._format_expected(expected, non_terminal)}"
         
-        # PRIORITY CHECK: Detect &&& operator (tokenized as && followed by &)
         if token_type == '&' and index > 0:
             prev_index = index - 1
             while prev_index >= 0 and toks[prev_index].type in self.skip_token_types:
@@ -249,10 +170,8 @@ class LL1Parser:
             
             if prev_index >= 0 and toks[prev_index].type == '&&':
                 return f"SYNTAX error line {line} col {col} Invalid operator '&&&'. Use '&&' for logical AND. {self._format_expected(expected, non_terminal)}"
-            # Single & without preceding &&
             return f"SYNTAX error line {line} col {col} Invalid operator '&'. Use '&&' for logical AND. {self._format_expected(expected, non_terminal)}"
         
-        # PRIORITY CHECK: Detect ||| operator (tokenized as || followed by |)
         if token_type == '|' and index > 0:
             prev_index = index - 1
             while prev_index >= 0 and toks[prev_index].type in self.skip_token_types:
@@ -260,23 +179,18 @@ class LL1Parser:
             
             if prev_index >= 0 and toks[prev_index].type == '||':
                 return f"SYNTAX error line {line} col {col} Invalid operator '|||'. Use '||' for logical OR. {self._format_expected(expected, non_terminal)}"
-            # Single | without preceding ||
             return f"SYNTAX error line {line} col {col} Invalid operator '|'. Use '||' for logical OR. {self._format_expected(expected, non_terminal)}"
         
-        # PRIORITY CHECK: Detect malformed literals in current token
         if token_type == 'chrlit' and token_value and not token_value.endswith("'"):
             return f"SYNTAX error line {line} col {col} Missing closing single quote in character literal. {self._format_expected(expected, non_terminal)}"
         
         if token_type == 'stringlit' and token_value and not token_value.endswith('"'):
             return f"SYNTAX error line {line} col {col} Missing closing double quote in string literal. {self._format_expected(expected, non_terminal)}"
         
-        # PRIORITY CHECK: Missing semicolon after 'reclaim'
         if non_terminal == '<reclaim_value>' and token_type == '}':
             return f"SYNTAX error line {line} col {col} Missing ';' after 'reclaim'. Unexpected token '{token_value}'. {self._format_expected(expected, non_terminal)}"
         
-        # Check for unmatched closing parenthesis
         if token_type == ')' and ')' not in expected:
-            # Check if previous token was a binary operator - if so, it's a missing operand issue
             if index > 0:
                 prev_index = index - 1
                 while prev_index >= 0 and toks[prev_index].type in self.skip_token_types:
@@ -288,11 +202,9 @@ class LL1Parser:
                     if prev_tok.type in binary_operators:
                         return f"SYNTAX error line {line} col {col} Unexpected token ')' after binary operator '{prev_tok.value}'. {self._format_expected(expected, non_terminal)}"
                     
-                    # Check for trailing comma in parameter list
                     if prev_tok.type == ',' and param_type_tokens & expected:
                         return f"SYNTAX error line {line} col {col}: Unexpected token ')'. Expected parameter type (seed, tree, leaf, vine, branch) after ','"
                     
-                    # Check if keyword( ) — user tried to use a reserved keyword as a function name
                     if prev_tok.type == '(':
                         kw_index = prev_index - 1
                         while kw_index >= 0 and toks[kw_index].type in self.skip_token_types:
@@ -316,15 +228,12 @@ class LL1Parser:
                                 desc = keyword_descriptions[kw_tok.type]
                                 return f"SYNTAX error line {kw_tok.line} col {kw_tok.col} '{kw_tok.value}' is a reserved keyword ({desc}) and cannot be used as a function name."
             
-            # Otherwise, it's an unmatched closing parenthesis
             return f"SYNTAX error line {line} col {col} Unexpected token ')' - no matching '(' found in expression. {self._format_expected(expected, non_terminal)}"
         
-        # Explain assignment operators that occur where no valid assignment can start.
         assignment_operators = {'+=', '-=', '*=', '/=', '%='}
         if token_type in assignment_operators:
             return f"SYNTAX error line {line} col {col} Assignment operator '{token_value}' must follow a modifiable assignment target. {self._format_expected(expected, non_terminal)}"
         
-        # Check for '=' after binary operator (likely space in compound assignment like 'a + = 2')
         if token_type == '=':
             if index > 0:
                 prev_index = index - 1
@@ -335,7 +244,6 @@ class LL1Parser:
                     prev_tok = toks[prev_index]
                     compound_op_bases = {'+', '-', '*', '/', '%'}
                     if prev_tok.type in compound_op_bases:
-                        # Check if there's an identifier before the operator
                         prev_prev_index = prev_index - 1
                         while prev_prev_index >= 0 and toks[prev_prev_index].type in self.skip_token_types:
                             prev_prev_index -= 1
@@ -345,12 +253,10 @@ class LL1Parser:
                             compound_op = f"{prev_tok.value}="
                             return f"SYNTAX error line {line} col {col} Unexpected token '=' after operator '{prev_tok.value}'. Did you mean '{id_tok.value} {compound_op}' (compound assignment with no space)? {self._format_expected(expected, non_terminal)}"
         
-        # Check for '{' at start of program - likely caused by lexical error preventing 'root' token
         if token_type == '{' and non_terminal in {'<program>', '<global_declaration>'}:
             if index == 0 or (index <= 2 and all(toks[i].type in self.skip_token_types for i in range(index))):
                 return f"SYNTAX error line {line} col {col} 'root' function declaration is missing opening '('. {self._format_expected(expected, non_terminal)}"
         
-        # Check next token if it exists (look-ahead for malformed literals)
         if index + 1 < len(toks):
             next_tok = toks[index + 1]
             if next_tok.type == 'chrlit' and next_tok.value and not next_tok.value.endswith("'"):
@@ -359,21 +265,17 @@ class LL1Parser:
             if next_tok.type == 'stringlit' and next_tok.value and not next_tok.value.endswith('"'):
                 return f"SYNTAX error line {next_tok.line} col {next_tok.col} Missing closing double quote in string literal. {self._format_expected(expected, non_terminal)}"
         
-        # Check for semicolon after bundle closing brace (common mistake)
         if token_type == ';' and non_terminal == '<global_declaration>':
-            # Look back to see if previous token was '}' from a bundle definition
             if index > 0:
                 prev_index = index - 1
                 while prev_index >= 0 and toks[prev_index].type in self.skip_token_types:
                     prev_index -= 1
                 
                 if prev_index >= 0 and toks[prev_index].type == '}':
-                    # Look further back to see if this was a bundle definition
                     bundle_index = prev_index - 1
                     while bundle_index >= 0 and toks[bundle_index].type in self.skip_token_types:
                         bundle_index -= 1
                     
-                    # Check if we can find 'bundle' keyword before this
                     found_bundle = False
                     for i in range(bundle_index, max(0, bundle_index - 20) - 1, -1):
                         if toks[i].type == 'bundle':
@@ -384,7 +286,6 @@ class LL1Parser:
                         expected_str = self._format_expected(expected, non_terminal)
                         return f"SYNTAX error line {line} col {col} Unexpected token ';' after bundle definition closing '}}'. ';' is not in {expected_str}. Remove the trailing ';'"
         
-        # Check for common invalid keywords from other languages (check early)
         common_keyword_mistakes = {
             'function': 'pollinate',
             'int': 'seed',
@@ -418,22 +319,16 @@ class LL1Parser:
             correct_keyword = common_keyword_mistakes[token_value]
             return f"SYNTAX error line {line} col {col} '{token_value}' is not a GAL keyword. Use '{correct_keyword}' instead."
         
-        # Check for bundle definition inside a function (common mistake)
         if token_type == '{' and (non_terminal == '<bundle_or_var>' or non_terminal == '<bundle_mem_dec>'):
-            # This means we saw "bundle id {" but inside a function body
-            # In global scope, this would be a bundle definition, but it's not allowed inside functions
             return f"SYNTAX error line {line} col {col} Bundle definitions must be at global scope (outside all functions). Move this bundle definition before 'root()'. {self._format_expected(expected, non_terminal)}"
         
-        # Check if semicolon is expected and we're seeing a keyword/statement starter
         statement_starters = {
             'reclaim', 'spring', 'wither', 'bud', 'grow', 'cultivate', 'tend',
             'harvest', 'prune', 'skip', 'water', 'plant', 'seed', 'leaf',
             'branch', 'tree', 'vine', 'bundle', 'fertile', 'pollinate', 'root', 'id'
         }
         
-        # Check for missing ':' after variety/soil expression (priority over ';' check)
         if ':' in expected and token_type in statement_starters:
-            # Walk back to find 'variety' or 'soil'
             context_keyword = None
             if index > 0:
                 scan = index - 1
@@ -447,7 +342,6 @@ class LL1Parser:
                     if toks[scan].type == 'soil':
                         context_keyword = 'soil'
                         break
-                    # Skip expression tokens between variety and here
                     if toks[scan].type in {'id', 'intlit', 'dblit', 'stringlit', 'chrlit',
                                            'sunshine', 'frost', '+', '-', '*', '/', '%',
                                            '==', '!=', '<', '>', '<=', '>=', '&&', '||',
@@ -460,8 +354,6 @@ class LL1Parser:
         
         if ';' in expected:
             if token_type in statement_starters or token_type == 'id':
-                # Look back at previous token to show what was incomplete
-                # Skip past newlines to find the actual meaningful previous token
                 if index > 0:
                     prev_index = index - 1
                     while prev_index >= 0 and toks[prev_index].type in self.skip_token_types:
@@ -470,19 +362,16 @@ class LL1Parser:
                     if prev_index >= 0:
                         prev_tok = toks[prev_index]
                         
-                        # Check if previous token is '=' (missing value in assignment)
                         if prev_tok.type == '=':
                             prev_line = prev_tok.line
                             prev_col = prev_tok.col
                             return f"SYNTAX error line {prev_line} col {prev_col} Missing value after '=' operator. {self._format_expected(expected, non_terminal)}"
                         
-                        # Check if previous token is a malformed character literal (missing closing quote)
                         if prev_tok.type == 'chrlit' and prev_tok.value and not prev_tok.value.endswith("'"):
                             prev_line = prev_tok.line
                             prev_col = prev_tok.col
                             return f"SYNTAX error line {prev_line} col {prev_col} Missing closing single quote in character literal. {self._format_expected(expected, non_terminal)}"
                         
-                        # Check if previous token is a malformed string literal (missing closing quote)
                         if prev_tok.type == 'stringlit' and prev_tok.value and not prev_tok.value.endswith('"'):
                             prev_line = prev_tok.line
                             prev_col = prev_tok.col
@@ -491,12 +380,11 @@ class LL1Parser:
                         prev_line = prev_tok.line
                         prev_col = prev_tok.col + len(str(prev_tok.value))
                         expected_str = self._format_expected(expected, non_terminal)
-                        if prev_line != line:  # Previous token on different line
+                        if prev_line != line:
                             return (f"SYNTAX error line {prev_line} col {prev_col} Unexpected token '{token_value}' after '{prev_tok.value}'. {expected_str}")
                         else:
                             return f"SYNTAX error line {line} col {col} Unexpected token '{token_value}'. {expected_str}"
             elif token_type == '}':
-                # Missing semicolon before closing brace
                 if index > 0:
                     prev_index = index - 1
                     while prev_index >= 0 and toks[prev_index].type in self.skip_token_types:
@@ -505,17 +393,14 @@ class LL1Parser:
                     if prev_index >= 0:
                         prev_tok = toks[prev_index]
                         
-                        # Check for missing ';' after 'reclaim'
                         if prev_tok.type == 'reclaim':
                             return f"SYNTAX error line {prev_tok.line} col {prev_tok.col + len('reclaim')} Missing ';' after 'reclaim'. {self._format_expected(expected, non_terminal)}"
                         
-                        # Check if previous token is a malformed character literal (missing closing quote)
                         if prev_tok.type == 'chrlit' and prev_tok.value and not prev_tok.value.endswith("'"):
                             prev_line = prev_tok.line
                             prev_col = prev_tok.col
                             return f"SYNTAX error line {prev_line} col {prev_col} Missing closing single quote in character literal. {self._format_expected(expected, non_terminal)}"
                         
-                        # Check if previous token is a malformed string literal (missing closing quote)
                         if prev_tok.type == 'stringlit' and prev_tok.value and not prev_tok.value.endswith('"'):
                             prev_line = prev_tok.line
                             prev_col = prev_tok.col
@@ -529,22 +414,18 @@ class LL1Parser:
                         else:
                             return f"SYNTAX error line {line} col {col} Unexpected token '}}'. {expected_str}"
         
-        # Check for missing reclaim statement
         if 'reclaim' in expected and token_type == '}':
             return f"SYNTAX error line {line} col {col} expected 'reclaim;' before '}}'. All functions, including root(), must end with 'reclaim;'. {self._format_expected(expected, non_terminal)}"
         
-        # Check for missing prune (break) in variety (case) statements
         if 'prune' in expected and token_type in {'variety', 'soil', '}'}:
             if token_type == 'variety':
                 return f"SYNTAX error line {line} col {col} expected 'prune;' before next 'variety'. Each case in 'harvest' must end with 'prune;'. {self._format_expected(expected, non_terminal)}"
             elif token_type == 'soil':
                 return f"SYNTAX error line {line} col {col} expected 'prune;' before 'soil'. Each case must end with 'prune;'. {self._format_expected(expected, non_terminal)}"
-            else:  # token_type == '}'
+            else:
                 return f"SYNTAX error line {line} col {col} expected 'prune;' before closing '}}'. Each case must end with 'prune;'. {self._format_expected(expected, non_terminal)}"
         
-        # Check for unary minus/plus usage (not supported in grammar) - must check BEFORE missing value error
         if token_type in {'-', '+'} and non_terminal in {'<expression>', '<factor>', '<term>', '<arithmetic>', '<logic_or>', '<logic_and>', '<relational>', '<init_val>'}:
-            # Look back to see what preceded this operator
             if index > 0:
                 prev_index = index - 1
                 while prev_index >= 0 and toks[prev_index].type in self.skip_token_types:
@@ -552,14 +433,12 @@ class LL1Parser:
                 
                 if prev_index >= 0:
                     prev_tok = toks[prev_index]
-                    # If preceded by assignment or operators, likely trying to use unary operator
                     if prev_tok.type in {'=', '+=', '-=', '*=', '/=', '%=', '(', ','}:
                         if token_value == '-':
                             return f"SYNTAX error line {line} col {col} Unary '-' not supported. Use '~' for negative numbers (e.g., '~5') or '(0 - value)' for negation. {self._format_expected(expected, non_terminal)}"
                         else:
                             return f"SYNTAX error line {line} col {col} Unary '+' operator not supported. Use parentheses for expressions like '(0 + value)'. {self._format_expected(expected, non_terminal)}"
         
-        # Check for binary operator after opening parenthesis (prefix notation attempt)
         if token_type in {'*', '/', '%', '+', '-', '`', '&&', '||', '==', '!=', '<', '>', '<=', '>='}:
             if index > 0:
                 prev_index = index - 1
@@ -569,10 +448,7 @@ class LL1Parser:
                 if prev_index >= 0 and toks[prev_index].type == '(':
                     return f"SYNTAX error line {line} col {col} Unexpected binary operator '{token_value}'. {self._format_expected(expected, non_terminal)}"
         
-        # Check for missing opening parenthesis
         if '(' in expected and token_type != '(':
-            # Check if previous token was an arithmetic/logical operator - missing operand case
-            # BUT skip if current token is +/- (handled above as unary operator case)
             if index > 0 and token_type not in {'-', '+'}:
                 prev_index = index - 1
                 while prev_index >= 0 and toks[prev_index].type in self.skip_token_types:
@@ -580,19 +456,14 @@ class LL1Parser:
                 
                 if prev_index >= 0:
                     prev_tok = toks[prev_index]
-                    # If an operator precedes the current token, user likely forgot an operand
                     if prev_tok.type in {'+', '-', '*', '/', '%', '`', '=', '+=', '-=', '*=', '/=', '%=', '&&', '||', '==', '!=', '<', '>', '<=', '>='}:
-                        # Check if current token is a binary operator
                         if token_type in {'*', '/', '%', '+', '-', '`', '&&', '||', '==', '!=', '<', '>', '<=', '>='}:
                             return f"SYNTAX error line {line} col {col} Unexpected token '{token_value}' operator - binary operators cannot start an expression. {self._format_expected(expected, non_terminal)}"
                         return f"SYNTAX error line {line} col {col} Missing value after '{prev_tok.value}' operator. {self._format_expected(expected, non_terminal)}"
             
-            # Don't report a misleading "missing parenthesis" message for a
-            # misplaced assignment operator.
             if token_type in {'=', '+=', '-=', '*=', '/=', '%='}:
                 return f"SYNTAX error line {line} col {col} Unexpected token '{token_value}'. {self._format_expected(expected, non_terminal)}"
             
-            # Look back to find the keyword/statement that needs parentheses
             if index > 0:
                 prev_index = index - 1
                 while prev_index >= 0 and toks[prev_index].type in self.skip_token_types:
@@ -601,7 +472,6 @@ class LL1Parser:
                 if prev_index >= 0:
                     prev_tok = toks[prev_index]
                     
-                    # Check if previous token was an invalid keyword from other languages
                     common_keyword_mistakes = {
                         'function': 'pollinate',
                         'int': 'seed',
@@ -635,22 +505,15 @@ class LL1Parser:
                         correct_keyword = common_keyword_mistakes[prev_tok.value]
                         return f"SYNTAX error line {prev_tok.line} col {prev_tok.col} '{prev_tok.value}' is not a GAL keyword. Use '{correct_keyword}' instead."
                     
-                    # Keywords that require parentheses
                     keywords_needing_parens = {'spring', 'grow', 'cultivate', 'harvest', 'water', 'plant', 'tend', 'bud'}
                     if prev_tok.type in keywords_needing_parens:
                         return f"SYNTAX error line {line} col {col} Missing '(' after '{prev_tok.value}'. {self._format_expected(expected, non_terminal)}"
                     
-                    # If previous token was an identifier, check context
                     if prev_tok.type == 'id':
                         # NOTE: GAL does support '**' (exponentiation) and '**=' (exponent-assign).
-                        # The old heuristic here used to reject both — removed when those operators
-                        # were enabled. A spaced '** =' is still invalid (lexer treats them as
-                        # two tokens) — fall through to the generic compound-assign hint below.
 
-                        # Check if current token is a binary operator followed by '=' (spaced compound assignment)
                         compound_op_bases = {'+', '-', '*', '/', '%'}
                         if token_type in compound_op_bases:
-                            # Look ahead to see if next token is '='
                             next_index = index + 1
                             while next_index < len(toks) and toks[next_index].type in self.skip_token_types:
                                 next_index += 1
@@ -659,16 +522,11 @@ class LL1Parser:
                                 compound_op = f"{token_value}="
                                 return f"SYNTAX error line {line} col {col} Unexpected operator '{token_value}' followed by '='. Expected: '{compound_op}' (compound assignment must be written without spaces). {self._format_expected(expected, non_terminal)}"
                         
-                        # Check if we're in an expression context by looking at expected tokens
-                        # If operators are expected, we're in expression context
                         binary_operators = {'+', '-', '*', '/', '%', '==', '!=', '<', '>', '<=', '>=', '&&', '||'}
                         has_operators_expected = bool(binary_operators & expected)
                         
                         if has_operators_expected:
-                           # In expression context: likely missing operator between identifier and next value
-                            # Special case: increment/decrement operators cannot be used in expressions
                             if token_type in {'++', '--'}:
-                                # Look ahead to see if there's another + or - (e.g., +++ or ---)
                                 next_index = index + 1
                                 while next_index < len(toks) and toks[next_index].type in self.skip_token_types:
                                     next_index += 1
@@ -680,27 +538,20 @@ class LL1Parser:
                                         return f"SYNTAX error line {line} col {col} Unexpected token '{operator_seq}' operator sequence. {self._format_expected(expected, non_terminal)}"
                                 
                                 return f"SYNTAX error line {line} col {col} Unexpected {token_type} operator. {self._format_expected(expected, non_terminal)}"
-                            # Look ahead to see what the current token is
                             if token_type in {'intlit', 'dblit', 'stringlit', 'chrlit', 'id'}:
                                 return f"SYNTAX error line {line} col {col} Unexpected token '{token_type}' after identifier '{prev_tok.value}'. {self._format_expected(expected, non_terminal)}"
                             else:
                                 return f"SYNTAX error line {line} col {col} Unexpected token '{token_value}' after identifier '{prev_tok.value}'. {self._format_expected(expected, non_terminal)}"
                         else:
-                            # In statement context: identifier used incorrectly as standalone statement
                             return f"SYNTAX error line {prev_tok.line} col {prev_tok.col} invalid statement: identifier '{prev_tok.value}' must be followed by assignment operator, unary operator (++/--), or function call syntax '()'. {self._format_expected(expected, non_terminal)}"
             
-            # Fallback message
             return f"SYNTAX error line {line} col {col} Unexpected token '{token_value}'. {self._format_expected(expected, non_terminal)}"
         
-        # A declaration token reaching the executable list means that this
-        # block already contains executable code.
         declaration_keywords = {'seed', 'tree', 'leaf', 'vine', 'branch', 'bundle', 'fertile'}
         if token_type in declaration_keywords and non_terminal in {'<body_statement>', '<statement>', '<case_statements>'}:
             return f"SYNTAX error line {line} col {col} Unexpected local declaration '{token_value}' after an executable statement. Local declarations must appear first in the block. {self._format_expected(expected, non_terminal)}"
 
-        # Check for missing closing braces
         if '}' in expected and token_type in statement_starters:
-            # Special case: bud/wither appearing without a preceding spring
             if token_type == 'bud':
                 return f"SYNTAX error line {line} col {col} 'bud' can only appear after a 'spring' statement. {self._format_expected(expected, non_terminal)}"
             elif token_type == 'wither':
@@ -709,28 +560,21 @@ class LL1Parser:
                 return f"SYNTAX error line {line} col {col} Missing closing brace before '{token_value}'. {self._format_expected(expected, non_terminal)}"
             return f"SYNTAX error line {line} col {col} Missing closing brace before '{token_value}'. {self._format_expected(expected, non_terminal)}"
         
-        # Check for ++ or -- operators used incorrectly in expressions
         if token_type in {'++', '--'} and ')' in expected:
             op_name = "increment" if token_value == "++" else "decrement"
             return f"SYNTAX error line {line} col {col} Postfix {op_name} operator '{token_value}' not allowed in expression context. {self._format_expected(expected, non_terminal)}"
         
-        # Check for missing parameter type in function declaration
         if param_type_tokens & expected and ')' in expected and token_type == 'id':
             return f"SYNTAX error line {line} col {col}: Unexpected token '{token_value}'. Expected parameter type (seed, tree, leaf, vine, branch) or ')'"
         
-        # Check for missing closing parenthesis
         if ')' in expected and token_type not in {')'}:
-            # Check for missing comma between function call arguments
             if ',' in expected and token_type in {'intlit', 'dblit', 'stringlit', 'chrlit', 'id', 'sunshine', 'frost', '~', '!'}:
                 return f"SYNTAX error line {line} col {col}: Unexpected token '{token_value}'. Expected ',' between arguments or ')' to close function call"
-            # Check if '~' or '!' (unary operators) appear where a binary operator is expected
             if token_type in {'~', '!'}:
                 return f"SYNTAX error line {line} col {col} Unexpected token '{token_value}'. {self._format_expected(expected, non_terminal)}"
             return f"SYNTAX error line {line} col {col} Unexpected token '{token_value}'. {self._format_expected(expected, non_terminal)}"
         
-        # Check for literal/identifier after identifier in expression context (missing operator)
         if token_type in {'intlit', 'dblit', 'stringlit', 'chrlit', 'id'}:
-            # Check if previous non-skipped token was also an identifier or literal
             if index > 0:
                 prev_index = index - 1
                 while prev_index >= 0 and toks[prev_index].type in self.skip_token_types:
@@ -738,9 +582,7 @@ class LL1Parser:
                 
                 if prev_index >= 0:
                     prev_tok = toks[prev_index]
-                    # If previous was identifier or literal, we're missing an operator
                     if prev_tok.type in {'id', 'intlit', 'dblit', 'stringlit', 'chrlit'}:
-                        # Check if we're in expression context
                         expression_contexts = {'<expression>', '<factor>', '<term>', '<arithmetic>', '<logic_or>', 
                                              '<logic_and>', '<relational>', '<init_val>', '<param_list>', '<arg_list>',
                                              '<term_tail>', '<arithmetic_tail>', '<relational_tail>', '<logic_and_tail>', '<logic_or_tail>'}
@@ -764,44 +606,24 @@ class LL1Parser:
                             
                             return f"SYNTAX error line {line} col {col} Unexpected {curr_type_friendly} '{token_value}' after {prev_type_friendly} '{prev_tok.value}'. {self._format_expected(expected, non_terminal)}"
         
-        # Check for variable used as array size — only constant integer literals allowed
         if non_terminal == '<array_dim_opt>' and token_type == 'id':
             return f"SYNTAX error line {line} col {col} Array size must be a constant integer literal, not a variable '{token_value}'. Expected: ']', dblit, intlit"
 
-        # Default message with helpful context
         return f"SYNTAX error line {line} col {col} Unexpected token '{token_value}'. {self._format_expected(expected, non_terminal)}"
 
-    # ========================================================================
-    # parse() - LL(1) SYNTAX VALIDATION (no AST built)
-    # The classic table-driven LL(1) algorithm: maintain a parse stack
-    # initialized with the start symbol, then for each input token either
-    # 'match' a terminal (pop stack + advance input) or 'expand' a
-    # non-terminal (look up table[NT][lookahead], push the production
-    # backwards onto the stack). Returns (success, error_messages_list).
-    # Used by /api/parse for syntax-only checking.
-    # ========================================================================
     def parse(self, tokens: Sequence[Any]) -> Tuple[bool, List[str]]:
-        """Parse tokens according to the supplied CFG/PREDICT sets.
-
-        Returns:
-            (success, errors) - stops at the first error encountered.
-        """
         toks = [_as_tok(t) for t in tokens]
         toks = [_TokView(self._normalize_token_type(t.type), t.value, t.line, t.col) for t in toks]
         toks = self._ensure_eof(toks)
 
-        # Store tokens so _format_expected can inspect the source
         self._current_tokens = toks
 
         stack: List[str] = [self.end_marker, self.start_symbol]
         index = 0
         
-        # Track variable declaration context for type checking
         current_var_type: Optional[str] = None
         expecting_value_for_type: Optional[str] = None
 
-        # Track whether 'reclaim' has been seen in the current block.
-        # Stack of booleans, one per nested { } block depth.
         reclaim_seen_stack: List[bool] = []
 
         def current_token() -> _TokView:
@@ -819,41 +641,31 @@ class LL1Parser:
             token_value = tok.value
             line = tok.line or 1
 
-            # Skip configured whitespace-like tokens unless grammar explicitly expects them.
             if token_type in self.skip_token_types and top != token_type:
                 index += 1
                 continue
 
-            # Expand non-terminal
             if top in self.parsing_table:
                 row = self.parsing_table[top]
                 if token_type in row:
                     production = row[token_type]
                     
-                    # Check for code after 'reclaim' in the current block
                     if top == '<statement>' and token_type != '}' and reclaim_seen_stack and reclaim_seen_stack[-1]:
                         return False, [f"SYNTAX error line {line} col {tok.col} Unexpected token '{token_value}' after 'reclaim'. Expected: '}}'."]
 
-                    # Check for empty blocks in conditionals/loops
-                    # When <statement> expands to epsilon and next token is '}', check if inside conditional/loop
                     if top == '<statement>' and token_type == '}':
                         is_epsilon = (len(production) == 0 or (len(production) == 1 and production[0] in self.epsilon_symbols))
                         if is_epsilon:
-                            # Look back to find the opening brace
                             lookback = index - 1
                             while lookback >= 0 and toks[lookback].type in self.skip_token_types:
                                 lookback -= 1
                             
-                            # If we immediately see '{' after skipping whitespace, it's an empty block
                             if lookback >= 0 and toks[lookback].type == '{':
-                                # Find what's before the brace
                                 before_brace = lookback - 1
                                 while before_brace >= 0 and toks[before_brace].type in self.skip_token_types:
                                     before_brace -= 1
                                 
-                                # Check if there's a ')' before the brace (conditional/loop pattern)
                                 if before_brace >= 0 and toks[before_brace].type == ')':
-                                    # Find the matching '(' and the keyword before it
                                     paren_depth = 1
                                     paren_pos = before_brace - 1
                                     while paren_pos >= 0 and paren_depth > 0:
@@ -863,7 +675,6 @@ class LL1Parser:
                                             paren_depth -= 1
                                         paren_pos -= 1
                                     
-                                    # Find keyword before the '('
                                     if paren_pos >= 0:
                                         kw_pos = paren_pos
                                         while kw_pos >= 0 and toks[kw_pos].type in self.skip_token_types:
@@ -871,19 +682,16 @@ class LL1Parser:
                                         
                                         if kw_pos >= 0:
                                             kw = toks[kw_pos]
-                                            # These keywords require at least one statement in their blocks
                                             conditional_keywords = {'spring', 'bud', 'wither', 'grow', 'cultivate', 'tend', 'harvest'}
                                             if kw.type in conditional_keywords:
                                                 return False, [f"SYNTAX error line {line} col {tok.col} Empty block after '{kw.value}' statement - at least one statement required"]
                                 
-                                # Check for wither/tend directly before '{' (no parentheses)
                                 elif before_brace >= 0 and toks[before_brace].type in {'wither', 'tend'}:
                                     kw = toks[before_brace]
                                     return False, [f"SYNTAX error line {line} col {tok.col} Empty block after '{kw.value}' statement - at least one statement required"]
                     
                     stack.pop()
 
-                    # Push RHS (unless epsilon)
                     if not (
                         len(production) == 0
                         or (len(production) == 1 and production[0] in self.epsilon_symbols)
@@ -893,48 +701,36 @@ class LL1Parser:
 
                 expected = set(row.keys())
                 
-                # Skip variety/soil outside harvest — let semantic analyzer handle the error
                 if token_type in {'variety', 'soil'} and token_type not in expected:
-                    # Skip past the entire variety/soil block
                     while index < len(toks) and toks[index].type != ';':
                         if toks[index].type == 'prune':
-                            index += 1  # skip 'prune'
+                            index += 1
                             break
                         index += 1
                     if index < len(toks) and toks[index].type == ';':
-                        index += 1  # skip ';'
+                        index += 1
                     continue
 
-                # Enhanced error messages for common mistakes
                 error_msg = self._generate_helpful_error(top, token_type, token_value, line, tok.col, expected, index, toks)
                 return False, [error_msg]
 
-            # Match terminal
             if top == token_type:
-                # Track variable type declarations
                 if token_type in {'seed', 'tree', 'leaf', 'branch', 'vine'}:
                     current_var_type = token_type
                     expecting_value_for_type = None
                 
-                # When we see '=', prepare to check the value
                 elif token_type == '=' and current_var_type is not None:
                     expecting_value_for_type = current_var_type
                 
-                # Check value type matches declared variable type
                 elif expecting_value_for_type is not None and token_type in {'intlit', 'dblit', 'stringlit', 'chrlit', 'sunshine', 'frost', 'id'}:
-                    # Type checking mapping
-                    # tree and branch reject identifiers; seed, leaf, vine allow them
-                    # seed also accepts dbllit (implicit truncation like C: int x = 4.5 → 4)
-                    # tree also accepts intlit (implicit promotion like C: double x = 5 → 5.0)
                     type_value_map = {
-                        'seed': {'intlit', 'dblit'},     # seed = integer, also accepts double (truncated)
-                        'tree': {'dblit', 'intlit'},     # tree = double, also accepts integer (promoted)
-                        'leaf': {'chrlit'},              # leaf = char (single character only, validated below)
-                        'branch': {'sunshine', 'frost'}, # branch = boolean (sunshine=true, frost=false only)
-                        'vine': {'stringlit'}            # vine = string only
+                        'seed': {'intlit', 'dblit'},
+                        'tree': {'dblit', 'intlit'},
+                        'leaf': {'chrlit'},
+                        'branch': {'sunshine', 'frost'},
+                        'vine': {'stringlit'}
                     }
                     
-                    # Allow identifiers for all types (semantic layer handles type checking)
                     if token_type == 'id':
                         expecting_value_for_type = None
                         stack.pop()
@@ -944,7 +740,6 @@ class LL1Parser:
                     expected_value_types = type_value_map.get(expecting_value_for_type, set())
                     
                     if token_type not in expected_value_types:
-                        # Generate helpful error message
                         type_names = {
                             'seed': 'integer (seed)',
                             'tree': 'double (tree)',
@@ -968,41 +763,30 @@ class LL1Parser:
                         error_msg = f"SEMANTIC error line {line} col {tok.col} Type mismatch: cannot assign {actual_type} value '{token_value}' to {declared_type} variable"
                         return False, [error_msg]
                     
-                    # Validate character literal length for leaf (char) type
                     if token_type == 'chrlit' and expecting_value_for_type == 'leaf':
-                        # Extract the actual character content (remove surrounding quotes)
-                        # Use slicing instead of strip to handle edge cases like '''
                         char_content = token_value[1:-1] if len(token_value) >= 2 else token_value
                         if len(char_content) == 0:
                             error_msg = f"SYNTAX error line {line} col {tok.col} Character literal cannot be empty. Expected a single character for leaf variable"
                             return False, [error_msg]
                         elif char_content.startswith('\\') and len(char_content) == 2:
-                            # Valid escape sequence like \n, \t, \\, \'
                             pass
                         elif len(char_content) > 1:
                             error_msg = f"SYNTAX error line {line} col {tok.col} Character literal '{token_value}' contains {len(char_content)} characters. leaf variables can only hold a single character"
                             return False, [error_msg]
                     
-                    # tree and branch now allow expressions — semantic layer handles type checking
                     
-                    # Reset after checking
                     expecting_value_for_type = None
                 
-                # Reset on semicolon (end of statement)
                 elif token_type == ';':
                     current_var_type = None
                     expecting_value_for_type = None
                 
-                # Check for numeric literal in control flow condition
                 if top == 'intlit' or top == 'dblit':
-                    # Look back to see if we're inside a control flow condition
-                    # Check if there's a '(' before this and a control flow keyword before that
                     lookback = index - 1
                     while lookback >= 0 and toks[lookback].type in self.skip_token_types:
                         lookback -= 1
                     
                     if lookback >= 0 and toks[lookback].type == '(':
-                        # Found '(', now check for control flow keyword before it
                         kw_pos = lookback - 1
                         while kw_pos >= 0 and toks[kw_pos].type in self.skip_token_types:
                             kw_pos -= 1
@@ -1011,7 +795,6 @@ class LL1Parser:
                             kw = toks[kw_pos]
                             condition_keywords = {'spring', 'grow', 'cultivate', 'tend', 'bud'}
                             if kw.type in condition_keywords:
-                                # Check if next token after the literal is ')' (meaning no comparison operator)
                                 next_idx = index + 1
                                 while next_idx < len(toks) and toks[next_idx].type in self.skip_token_types:
                                     next_idx += 1
@@ -1019,9 +802,7 @@ class LL1Parser:
                                 if next_idx < len(toks) and toks[next_idx].type == ')':
                                     return False, [f"SYNTAX error line {line} col {tok.col} '{kw.value}' requires a boolean condition, not a numeric literal"]
                 
-                # Check for logical operators used with non-branch operands
                 if token_type in {'&&', '||'}:
-                    # Look back to find the previous operand
                     prev_idx = index - 1
                     while prev_idx >= 0 and toks[prev_idx].type in self.skip_token_types:
                         prev_idx -= 1
@@ -1029,14 +810,12 @@ class LL1Parser:
                         prev_tok = toks[prev_idx]
                         non_branch_literals = {'intlit', 'dblit', 'stringlit', 'chrlit'}
                         if prev_tok.type in non_branch_literals:
-                            # Check if this literal is the RHS of a comparison operator
-                            # e.g. age < 1 || ... -> '1' is part of 'age < 1' (boolean)
                             cmp_idx = prev_idx - 1
                             while cmp_idx >= 0 and toks[cmp_idx].type in self.skip_token_types:
                                 cmp_idx -= 1
                             comparison_ops = {'<', '>', '<=', '>=', '==', '!='}
                             if cmp_idx >= 0 and toks[cmp_idx].type in comparison_ops:
-                                pass  # literal is part of a comparison expression (boolean)
+                                pass
                             else:
                                 type_names = {
                                     'intlit': 'integer literal',
@@ -1047,21 +826,17 @@ class LL1Parser:
                                 op_name = 'AND' if token_type == '&&' else 'OR'
                                 return False, [f"SYNTAX error line {line} col {tok.col} Logical operator '{token_type}' ({op_name}) requires branch operands, not {type_names[prev_tok.type]} '{prev_tok.value}'"]
                 
-                # Check for non-branch literal after logical operators
                 if token_type in {'intlit', 'dblit', 'stringlit', 'chrlit'}:
                     prev_idx = index - 1
                     while prev_idx >= 0 and toks[prev_idx].type in self.skip_token_types:
                         prev_idx -= 1
                     if prev_idx >= 0 and toks[prev_idx].type in {'&&', '||'}:
-                        # Check if next token after this literal is a comparison operator
-                        # e.g. ... || age > 120 -> 'age' after || is id not literal, but also
-                        # check if this literal is the LHS of a comparison (unlikely but safe)
                         next_check = index + 1
                         while next_check < len(toks) and toks[next_check].type in self.skip_token_types:
                             next_check += 1
                         comparison_ops = {'<', '>', '<=', '>=', '==', '!='}
                         if next_check < len(toks) and toks[next_check].type in comparison_ops:
-                            pass  # literal is part of a comparison expression (boolean)
+                            pass
                         else:
                             type_names = {
                                 'intlit': 'integer literal',
@@ -1072,7 +847,6 @@ class LL1Parser:
                             op_name = 'AND' if toks[prev_idx].type == '&&' else 'OR'
                             return False, [f"SYNTAX error line {line} col {tok.col} Logical operator '{toks[prev_idx].type}' ({op_name}) requires branch operands, not {type_names[token_type]} '{token_value}'"]
 
-                # Track reclaim and block depth
                 if token_type == '{':
                     reclaim_seen_stack.append(False)
                 elif token_type == '}':
@@ -1086,7 +860,6 @@ class LL1Parser:
                 index += 1
                 continue
 
-            # If the stack expects EOF but we still have skippable tokens, skip them.
             if top == self.end_marker and token_type in self.skip_token_types:
                 index += 1
                 continue
@@ -1094,15 +867,11 @@ class LL1Parser:
             expected = {top}
             shown_value = "end of file" if token_type == self.end_marker else token_value
             
-            # PRIORITY: Handle EOF hitting any expected terminal
             if token_type == self.end_marker:
                 error_msg = f"SYNTAX error line {line} col {tok.col} Unexpected end of file. Expected: '{top}'. Missing closing '}}' or incomplete statement."
                 return False, [error_msg]
             
-            # Enhanced error messages for specific missing tokens
-            # Check for missing 'grow' after tend { ... }
             if top == 'grow' and token_type == '(':
-                # Look back to see if we're inside a tend statement
                 scan_idx = index - 1
                 while scan_idx >= 0 and toks[scan_idx].type in self.skip_token_types:
                     scan_idx -= 1
@@ -1123,7 +892,6 @@ class LL1Parser:
                         return False, [error_msg]
             
             if top == 'reclaim' and token_type == '}':
-                # Check if we're in root() function vs regular function
                 is_root = False
                 for i in range(index - 1, -1, -1):
                     if toks[i].type == 'root':
@@ -1147,8 +915,6 @@ class LL1Parser:
                     error_msg = f"SYNTAX error line {line} col {tok.col} expected 'prune;' before closing '}}'. Each case must end with 'prune;'. {self._format_expected(expected)}"
                 return False, [error_msg]
             elif top == '(' and token_type != '(':
-                # Don't give a misleading "missing opening parenthesis" message
-                # when an assignment operator is misplaced.
                 if token_type in {'=', '+=', '-=', '*=', '/=', '%='}:
                     error_msg = f"SYNTAX error line {line} col {tok.col} Unexpected token '{token_value}'. {self._format_expected(expected, top)}"
                 elif index > 0:
@@ -1159,9 +925,7 @@ class LL1Parser:
                     if prev_index >= 0:
                         prev_tok = toks[prev_index]
                         
-                        # Special case: tend requires condition after closing brace
                         if prev_tok.type == '}':
-                            # Look back to find 'tend' keyword
                             brace_depth = 1
                             scan_idx = prev_index - 1
                             while scan_idx >= 0 and brace_depth > 0:
@@ -1171,7 +935,6 @@ class LL1Parser:
                                     brace_depth -= 1
                                 scan_idx -= 1
                             
-                            # Now check if 'tend' is before the opening brace
                             if scan_idx >= 0:
                                 kw_idx = scan_idx
                                 while kw_idx >= 0 and toks[kw_idx].type in self.skip_token_types:
@@ -1195,7 +958,6 @@ class LL1Parser:
                     error_msg = f"SYNTAX error line {line} col {tok.col} Unexpected token '{token_value}'. {self._format_expected(expected)}"
                 return False, [error_msg]
             elif top == '{' and token_type != '{':
-                # Check for extra closing parenthesis - common mistake like root())
                 error_msg = None
                 if token_type == ')' and index > 0:
                     prev_index = index - 1
@@ -1203,8 +965,6 @@ class LL1Parser:
                         prev_index -= 1
                     
                     if prev_index >= 0 and toks[prev_index].type == ')':
-                        # Two consecutive `)` - likely extra closing paren
-                        # Find the keyword before the first `)`
                         paren_index = prev_index - 1
                         paren_count = 1
                         while paren_index >= 0 and paren_count > 0:
@@ -1224,7 +984,6 @@ class LL1Parser:
                                 if kw_tok.type in {'root', 'pollinate'}:
                                     error_msg = f"SYNTAX error line {line} col {tok.col} Extra closing ')' after '{kw_tok.value}()'. Correct syntax: {kw_tok.value}(){{ ... }}. {self._format_expected(expected)}"
                 
-                # Missing opening brace - look back to find the keyword
                 if error_msg is None and index > 0:
                     prev_index = index - 1
                     while prev_index >= 0 and toks[prev_index].type in self.skip_token_types:
@@ -1232,11 +991,9 @@ class LL1Parser:
                     
                     if prev_index >= 0:
                         prev_tok = toks[prev_index]
-                        # Keywords/tokens that require braces
                         keywords_needing_braces = {'spring', 'wither', 'grow', 'cultivate', 'tend', 'harvest', 'bud', ')', 'pollinate', 'root'}
                         if prev_tok.type in keywords_needing_braces:
                             if prev_tok.type == ')':
-                                # Look further back to find the keyword before the closing paren
                                 paren_index = prev_index - 1
                                 paren_count = 1
                                 while paren_index >= 0 and paren_count > 0:
@@ -1246,7 +1003,6 @@ class LL1Parser:
                                         paren_count -= 1
                                     paren_index -= 1
                                 
-                                # Now find the keyword before the opening paren
                                 if paren_index >= 0:
                                     kw_index = paren_index
                                     while kw_index >= 0 and toks[kw_index].type in self.skip_token_types:
@@ -1276,7 +1032,6 @@ class LL1Parser:
             elif top == ')' and token_type != ')':
                 return False, [f"SYNTAX error line {line} col {tok.col} Unexpected token '{token_value}'. {self._format_expected(expected)}"]
             elif top == ':' and token_type != ':':
-                # Missing colon — look back to find 'variety' or 'soil' keyword for context
                 context_keyword = None
                 if index > 0:
                     prev_index = index - 1
@@ -1284,11 +1039,9 @@ class LL1Parser:
                         prev_index -= 1
                     if prev_index >= 0:
                         prev_tok = toks[prev_index]
-                        # For 'soil' the colon comes immediately after: soil :
                         if prev_tok.type == 'soil':
                             context_keyword = 'soil'
                         else:
-                            # For 'variety expr :' — walk back past expression to find 'variety'
                             scan = prev_index
                             while scan >= 0:
                                 if toks[scan].type in self.skip_token_types:
@@ -1297,7 +1050,6 @@ class LL1Parser:
                                 if toks[scan].type == 'variety':
                                     context_keyword = 'variety'
                                     break
-                                # Skip over expression tokens (literals, ids, operators, parens)
                                 if toks[scan].type in {'id', 'intlit', 'dblit', 'stringlit', 'chrlit',
                                                        'sunshine', 'frost', '+', '-', '*', '/', '%',
                                                        '==', '!=', '<', '>', '<=', '>=', '&&', '||',
@@ -1310,8 +1062,6 @@ class LL1Parser:
                 else:
                     return False, [f"SYNTAX error line {line} col {tok.col} Unexpected token '{token_value}'. {self._format_expected({':'})}"]
             elif top == ';' and token_type != ';':
-                # Missing semicolon - but check if this might be an invalid keyword used as a function
-                # Pattern: "if (condition) {" where parser saw "if()" as a function call  
                 common_keyword_mistakes = {
                     'function': 'pollinate', 'int': 'seed', 'float': 'tree', 'double': 'tree',
                     'char': 'leaf', 'bool': 'branch', 'boolean': 'branch', 'if': 'spring',
@@ -1323,15 +1073,12 @@ class LL1Parser:
                 }
                 
                 error_msg = None
-                # Check if current token is '{' after what looks like a function call with invalid keyword
                 if token_type == '{' and index > 0:
-                    # Look back for a closing parenthesis
                     paren_idx = index - 1
                     while paren_idx >= 0 and toks[paren_idx].type in self.skip_token_types:
                         paren_idx -= 1
                     
                     if paren_idx >= 0 and toks[paren_idx].type == ')':
-                        # Find the matching opening parenthesis
                         paren_depth = 1
                         paren_idx -= 1
                         while paren_idx >= 0 and paren_depth > 0:
@@ -1341,7 +1088,6 @@ class LL1Parser:
                                 paren_depth -= 1
                             paren_idx -= 1
                         
-                        # Check token before the opening parenthesis
                         if paren_idx >= 0:
                             id_idx = paren_idx
                             while id_idx >= 0 and toks[id_idx].type in self.skip_token_types:
@@ -1352,12 +1098,10 @@ class LL1Parser:
                                 correct_keyword = common_keyword_mistakes[keyword_tok.value]
                                 error_msg = f"SYNTAX error line {keyword_tok.line} col {keyword_tok.col} '{keyword_tok.value}' is not a GAL keyword. Use '{correct_keyword}' instead."
                 
-                # Check if CURRENT token (the one we're looking at) is an invalid keyword
                 if error_msg is None and token_type == 'id' and token_value in common_keyword_mistakes:
                     correct_keyword = common_keyword_mistakes[token_value]
                     error_msg = f"SYNTAX error line {line} col {tok.col} '{token_value}' is not a GAL keyword. Use '{correct_keyword}' instead."
                 
-                # Check for chained increment/decrement operators (e.g., a++++)
                 if error_msg is None and token_type in {'++', '--'} and index > 0:
                     prev_index = index - 1
                     while prev_index >= 0 and toks[prev_index].type in self.skip_token_types:
@@ -1368,7 +1112,6 @@ class LL1Parser:
                         if prev_tok.type in {'++', '--'}:
                             error_msg = f"SYNTAX error line {line} col {tok.col} Unexpected token '{token_value}' after '{prev_tok.value}'. Increment/decrement operators cannot be chained. {self._format_expected(expected)}"
                 
-                # Check for binary operator after increment/decrement (e.g., a--+2)
                 binary_operators = {'+', '-', '*', '/', '%', '==', '!=', '<', '>', '<=', '>=', '&&', '||'}
                 if error_msg is None and token_type in binary_operators and index > 0:
                     prev_index = index - 1
@@ -1380,7 +1123,6 @@ class LL1Parser:
                         if prev_tok.type in {'++', '--'}:
                             error_msg = f"SYNTAX error line {line} col {tok.col} Unexpected binary operator '{token_value}' after unary operator '{prev_tok.value}'. Increment/decrement must be standalone statements. {self._format_expected(expected)}"
                 
-                # Otherwise, it's a missing semicolon - report on the line where it should be added
                 if error_msg is None:
                     if index > 0:
                         prev_index = index - 1
@@ -1389,9 +1131,8 @@ class LL1Parser:
                         
                         if prev_index >= 0:
                             prev_tok = toks[prev_index]
-                            # Report error on the line of the previous token (where semicolon should be)
                             error_msg = f"SYNTAX error line {prev_tok.line} col {prev_tok.col + len(str(prev_tok.value))} Unexpected token '{token_value}'. Expected ';'. {self._format_expected(expected)}"
-                            line = prev_tok.line  # Use prev_tok line for deduplication
+                            line = prev_tok.line
                         else:
                             error_msg = f"SYNTAX error line {line} col {tok.col} Unexpected token '{token_value}'. Expected ';'. {self._format_expected(expected)}"
                     else:
@@ -1399,8 +1140,6 @@ class LL1Parser:
                 
                 return False, [error_msg]
             else:
-                # Check if missing return type in function declaration
-                # e.g. pollinate add(...) — 'add' consumed as return type, parser expects id for function name, sees '('
                 if top == 'id' and token_type == '(' and index > 0:
                     prev_index = index - 1
                     while prev_index >= 0 and toks[prev_index].type in self.skip_token_types:
@@ -1413,13 +1152,10 @@ class LL1Parser:
                             func_name = toks[prev_index].value
                             return False, [f"SYNTAX error line {toks[kw_index].line} col {toks[kw_index].col} Missing return type after 'pollinate'. '{func_name}' was parsed as the return type, not the function name. Expected: 'branch', 'empty', 'leaf', 'seed', 'tree', 'vine'"]
 
-                # Check if we're expecting a parameter name after an identifier was consumed as a bundle type
-                # e.g. pollinate seed add(seed a, b) — 'b' consumed as bundle type, parser expects 'id' for param name, but sees ')'
                 if top == 'id' and token_type == ')' and index > 0:
                     prev_index = index - 1
                     while prev_index >= 0 and toks[prev_index].type in self.skip_token_types:
                         prev_index -= 1
-                    # If prev token is an id that follows a ','  it's a missing param type
                     if prev_index >= 0 and toks[prev_index].type == 'id':
                         comma_index = prev_index - 1
                         while comma_index >= 0 and toks[comma_index].type in self.skip_token_types:
@@ -1429,13 +1165,11 @@ class LL1Parser:
                             param_expected = {'seed', 'tree', 'leaf', 'vine', 'branch'}
                             return False, [f"SYNTAX error line {toks[prev_index].line} col {toks[prev_index].col} Missing type for parameter '{param_name}'. Each parameter requires a type. {self._format_expected(param_expected)}"]
 
-                # Use the helper method for better error messages
                 error_msg = self._generate_helpful_error(
                     top, token_type, token_value, line, tok.col, expected, index, toks
                 )
                 return False, [error_msg]
 
-        # Consume trailing skippables then require EOF
         while index < len(toks) and toks[index].type in self.skip_token_types:
             index += 1
         if index < len(toks) and toks[index].type != self.end_marker:
@@ -1446,25 +1180,7 @@ class LL1Parser:
         
         return True, []
 
-    # ========================================================================
-    # parse_and_build() - SYNTAX + AST CONSTRUCTION (full parser entry)
-    # First runs the LL(1) check; if it passes, delegates to
-    # GALsemantic.build_ast which walks the same token stream and
-    # constructs the AST. Some semantic errors (undeclared variables,
-    # duplicate functions) are caught during AST construction and reported
-    # with error_stage='semantic' so the IDE can label them correctly.
-    # Used by /api/semantic, /api/icg, /api/run, and Socket.IO 'run_code'.
-    # ========================================================================
     def parse_and_build(self, tokens: Sequence[Any]):
-        """Validate syntax with LL(1) grammar, then build AST.
-
-        This is the main parser entry point for the full pipeline:
-            tokens  →  LL(1) syntax check  →  AST construction
-
-        Returns:
-            dict with keys: success, errors, ast, symbol_table
-        """
-        # Step 1: LL(1) syntax validation
         syntax_ok, syntax_errors = self.parse(tokens)
         if not syntax_ok:
             return {
@@ -1474,12 +1190,10 @@ class LL1Parser:
                 "symbol_table": {},
             }
 
-        # Step 2: Build AST from the validated token stream
         try:
             filtered = [t for t in tokens if getattr(t, 'type', '') != '\n']
             ast = _build_ast(filtered)
 
-            # Serialize the symbol table produced during AST construction
             st = {
                 "variables": [
                     {
@@ -1523,4 +1237,3 @@ class LL1Parser:
             }
 
 
-

Backend/semantic/__init__.py

@@ -1,9 +1,3 @@
-# ============================================================================
-# SEMANTIC PACKAGE - Symbol table + tree-walking AST validator
-# ============================================================================
-# Public API:
-#     from semantic import SymbolTable, validate_ast, ASTValidator
-# ============================================================================
 
 from .symbol_table import SymbolTable  # noqa: F401
 from .analyzer import ASTValidator, validate_ast  # noqa: F401

Backend/semantic/analyzer.py

@@ -1,24 +1,7 @@
-# ============================================================================
-# SEMANTIC ANALYZER - Tree-walking validator for the completed AST
-# ============================================================================
-# Extracted from GALsemantic.py during the modular restructure.
-# The parser already does primary checks during AST construction. This
-# validator does the SECOND pass over the completed tree to catch checks
-# that need a global view (function arity, return-path coverage, etc.).
-# ============================================================================
 from semantic.errors import SemanticError
 
 
 class ASTValidator:
-    """Tree-walking semantic validator.
-
-    Receives an already-built AST and walks every node to verify:
-      • Variable declarations are well-formed
-      • Function declarations have names and return types
-      • Break/continue appear only inside loops or switches
-      • Loop and conditional bodies are present
-      • Expressions have valid structure
-    """
 
     def __init__(self):
         self.errors = []
@@ -28,10 +11,8 @@ class ASTValidator:
         self._in_function = False
         self._current_func_type = None
 
-    # ── public entry point ──────────────────────────────────────────
 
     def validate(self, ast, symbol_table_data):
-        """Validate *ast* and return a result dict."""
         self._walk(ast)
         return {
             "success": len(self.errors) == 0,
@@ -41,7 +22,6 @@ class ASTValidator:
             "ast": ast,
         }
 
-    # ── recursive walker ────────────────────────────────────────────
 
     def _walk(self, node):
         if node is None:
@@ -50,11 +30,9 @@ class ASTValidator:
         if handler:
             handler(node)
         else:
-            # Default: visit all children
             for child in getattr(node, 'children', []):
                 self._walk(child)
 
-    # ── node-specific validators ────────────────────────────────────
 
     def _check_Program(self, node):
         for child in node.children:
@@ -72,7 +50,6 @@ class ASTValidator:
             self._walk(child)
 
     def _check_SturdyDeclaration(self, node):
-        # fertile (constant) declaration
         if len(node.children) < 3:
             self.errors.append(
                 f"Ln {node.line} Semantic Error: Fertile declaration must have type, name, and value.")
@@ -86,7 +63,6 @@ class ASTValidator:
         prev_in_func = self._in_function
         prev_func_type = self._current_func_type
         self._in_function = True
-        # Return type is in the first child
         if node.children:
             self._current_func_type = node.children[0].value
         for child in node.children:
@@ -222,25 +198,6 @@ class ASTValidator:
             self._walk(child)
 
 
-# ============================================================================
-# validate_ast() - PUBLIC SEMANTIC-ANALYSIS ENTRY POINT
-# Used by server.py after parse_and_build succeeds. Wraps ASTValidator.
-# Returns a dict with success/errors/warnings/symbol_table/ast.
-# ============================================================================
 def validate_ast(ast, symbol_table_data):
-    """Public API: validate an already-built AST.
-
-    This is the semantic analysis phase of the compiler pipeline.
-    The parser has already built the AST (with primary checks during
-    construction).  This function performs a tree-walking validation
-    pass over the completed AST.
-
-    Args:
-        ast: The root AST node (ProgramNode) produced by the parser.
-        symbol_table_data: Serialized symbol table dict from the parser.
-
-    Returns:
-        dict with keys: success, errors, warnings, symbol_table, ast
-    """
     validator = ASTValidator()
     return validator.validate(ast, symbol_table_data)

Backend/semantic/errors.py

@@ -1,10 +1,3 @@
-# ============================================================================
-# SEMANTIC ERROR - Raised during AST construction / validation
-# ============================================================================
-# Raised by parser/builder.py (during AST construction) and by
-# semantic/analyzer.py (during the final tree-walking validation pass).
-# Includes the source line so the IDE can highlight the right location.
-# ============================================================================
 
 
 class SemanticError(Exception):

Backend/semantic/symbol_table.py

@@ -1,31 +1,19 @@
-# ============================================================================
-# SYMBOL TABLE - Declaration tracker for the AST builder
-# ============================================================================
-# Extracted from GALsemantic.py during the modular restructure.
-# Used by parser/builder.py during AST construction to track variables,
-# functions, bundles, and scopes; the populated table is then serialized
-# (in parser/parser.py) and passed to semantic/analyzer.py for the second
-# semantic pass.
-# ============================================================================
 
 
 class SymbolTable:
     def __init__(self):
-        self.variables = {}  # Stores variables
-        self.global_variables = {}  # Stores global variables
-        self.functions = {}  # Stores function definitions
-        self.scopes = [{}]   # Stack of scopes (for local/global tracking)
+        self.variables = {}
+        self.global_variables = {}
+        self.functions = {}
+        self.scopes = [{}]
         self.current_func_name = None
         self.function_variables = {}
-        self.bundle_types = {}  # Stores bundle (struct) type definitions
+        self.bundle_types = {}
 
-    ###### VARIABLE ######
     def declare_variable(self, name, type_, value=None, is_list=False, is_fertile=False):
         scope = self.scopes[-1]
         current_func = self.current_func_name
     
-        #for i, s in enumerate(self.scopes):
-            #print(f"[SCOPE {i}] {s}")
 
         if name in self.functions:
             return f"Semantic Error: Variable '{name}' already declared as a function."
@@ -59,7 +47,6 @@ class SymbolTable:
             }
         
 
-
     def lookup_variable(self, name):
         for i, scope in enumerate(reversed(self.scopes)):
             if name in scope:
@@ -78,7 +65,6 @@ class SymbolTable:
         else:
             return f"Semantic Error: Variable '{name}' not declared in the current scope."
 
-    ###### FUNCTION ######
     def declare_function(self, name, return_type, params, node=None):
         if name in self.functions:
             return f"Semantic Error: Function '{name}' already declared."
@@ -90,7 +76,6 @@ class SymbolTable:
         return f"Semantic Error: Function '{name}' is not defined."
     
 
-    ###### SCOPE ######
     def enter_scope(self):
         self.scopes.append({})
         
@@ -114,15 +99,3 @@ class SymbolTable:
         print("================================\n")
 
 
-
-# ============================================================================
-# BUILD AST + parse_* HELPERS - Moved to parser/builder.py (Phase 5b).
-# No re-export here because that would create a circular import:
-#     parser.builder imports SymbolTable from here, so we can't also import
-#     back from parser.builder.
-# External callers should import directly from the new location:
-#     from parser.builder import build_ast, symbol_table, analyze_semantics
-# ============================================================================
-
-
-

Backend/server.py

@@ -1,52 +1,27 @@
-# ============================================================================
-# GAL COMPILER SERVER - HTTP + WebSocket entry point
-# ============================================================================
-# This is the orchestrator of the entire compiler. It exposes Flask routes
-# for each compiler stage (lex / parse / semantic / icg / run) and Socket.IO
-# events for interactive program execution. Every request flows through:
-#
-#     source code -> lexer -> parser+AST -> semantic -> ICG -> interpreter
-#
-# Each stage short-circuits on failure so the user sees the FIRST stage that
-# rejected their code, not a flood of cascading errors.
-# ============================================================================
-
-# ============================================================================
+
 # WARNING SUPPRESSION + EVENTLET BOOTSTRAP
-# Eventlet provides cooperative concurrency so Socket.IO can park a request
-# (e.g. waiting on water() input) without blocking the whole server.
-# monkey_patch() must run BEFORE flask/socketio are imported.
-# ============================================================================
 import warnings
 warnings.filterwarnings("ignore", message=".*RLock.*were not greened.*")
 
 import eventlet
 eventlet.monkey_patch()
 
-# ============================================================================
-# IMPORTS - Flask web framework + every layer of the GAL compiler
-# ============================================================================
 from flask import Flask, request, jsonify, send_from_directory
 from flask_cors import CORS
 from flask_socketio import SocketIO, emit
 import os
-from google import genai                                       # AI chat helper (optional)
-from lexer import lex, get_token_description                   # Stage 1: Lexical
-from parser import LL1Parser                                   # Stage 2: Syntax (LL(1))
-from cfg import cfg, first_sets, predict_sets                  # Grammar + parse table
-from parser.builder import analyze_semantics                   # Stage 3a: legacy entry
-from semantic import validate_ast                              # Stage 3b: Semantic validator
-from icg import generate_icg                                   # Stage 4: ICG (display)
-from interpreter import Interpreter, InterpreterError, _CancelledError      # Stage 5: Run
-from ai import fallback_reply                                  # Rule-based AI fallback
-
-
-# ============================================================================
-# DISPLAY HELPER - Escapes control characters so token values are safe
-# to embed in JSON responses for the IDE's lexeme table.
-# ============================================================================
+from google import genai
+from lexer import lex, get_token_description
+from parser import LL1Parser
+from cfg import cfg, first_sets, predict_sets
+from parser.builder import analyze_semantics
+from semantic import validate_ast
+from icg import generate_icg
+from interpreter import Interpreter, InterpreterError, _CancelledError
+from ai import fallback_reply
+
+
 def _display_value(val):
-    """Escape special chars in token values for safe display (like C's repr)."""
     if val is None:
         return ''
     s = str(val)
@@ -56,54 +31,33 @@ def _display_value(val):
     return s
 
 
-# ============================================================================
-# FLASK APP INITIALIZATION
-# ============================================================================
 app = Flask(__name__, static_folder='../UI', static_url_path='')
-CORS(app)                                                       # Allow browser frontend on any origin (dev)
-socketio = SocketIO(app, cors_allowed_origins="*")              # WebSocket layer for live program execution
+CORS(app)
+socketio = SocketIO(app, cors_allowed_origins="*")
 
-# Per-session interpreter registry (sid -> Interpreter instance).
-# One user can only have one program running at a time; new runs cancel the old.
 interpreters = {}
 
 
-# ============================================================================
-# SESSION EMITTER - Routes interpreter output to the originating browser
-# session instead of broadcasting to every connected client.
-# ============================================================================
 class SessionEmitter:
-    """Wrapper around SocketIO that always emits to a specific client session."""
     def __init__(self, sio, sid):
-        self._sio = sio                                         # the global SocketIO instance
-        self._sid = sid                                         # this client's session ID
+        self._sio = sio
+        self._sid = sid
 
     def emit(self, event, data=None, **kwargs):
-        # Always 'to=sid' so output goes to one user, never broadcast
         self._sio.emit(event, data, to=self._sid, **kwargs)
 
 
-# ============================================================================
-# PARSER SINGLETON - Built once at startup; the LL(1) parser is stateless
-# across calls so this instance is shared by every request.
-# ============================================================================
 parser = LL1Parser(
-    cfg=cfg,                            # Grammar productions
-    predict_sets=predict_sets,          # Pre-computed parse table
-    first_sets=first_sets,              # FIRST sets (for error recovery hints)
-    start_symbol="<program>",           # Top of the GAL grammar
-    end_marker="EOF",                   # Matches the synthetic EOF token from the lexer
-    skip_token_types={'\n'}             # Newlines are filtered before the parser sees them
+    cfg=cfg,
+    predict_sets=predict_sets,
+    first_sets=first_sets,
+    start_symbol="<program>",
+    end_marker="EOF",
+    skip_token_types={'\n'}
 )
 
-# ============================================================================
-# STATIC FILE SERVING - Serves the IDE's HTML/CSS/JS/images so the whole app
-# works as a single deployable. The no-cache header prevents stale UI during
-# development.
-# ============================================================================
 @app.after_request
 def add_no_cache(response):
-    """Prevent browser from caching static files during development."""
     response.headers['Cache-Control'] = 'no-store, no-cache, must-revalidate, max-age=0'
     response.headers['Pragma'] = 'no-cache'
     response.headers['Expires'] = '0'
@@ -111,32 +65,19 @@ def add_no_cache(response):
 
 @app.route('/')
 def index():
-    """Serve the main HTML file"""
     return send_from_directory('../UI', 'index.html')
 
 @app.route('/images/<path:filename>')
 def serve_images(filename):
-    """Serve image files from root images folder"""
     return send_from_directory('../images', filename)
 
 @app.route('/<path:path>')
 def serve_static(path):
-    """Serve static files (CSS, JS, etc.) from UI folder"""
     return send_from_directory('../UI', path)
 
 
-# ============================================================================
-# API ENDPOINT: /api/lex  - LEXICAL ANALYSIS (stage 1 only)
-# Returns the token stream and any lexical errors. Used by the IDE's
-# "Lexemes" tab to display the token table.
-# ============================================================================
 @app.route('/api/lex', methods=['POST'])
 def lexer_endpoint():
-    """
-    API endpoint for lexical analysis
-    Expects JSON: {"source_code": "your GAL code here"}
-    Returns JSON: {"tokens": [...], "errors": [...]}
-    """
     try:
         data = request.get_json()
         
@@ -147,10 +88,8 @@ def lexer_endpoint():
         
         source_code = data['source_code']
         
-        # Run the lexer
         tokens, errors = lex(source_code)
         
-        # Convert tokens to serializable format
         token_list = []
         for token in tokens:
             token_list.append({
@@ -171,19 +110,8 @@ def lexer_endpoint():
             'error': f'Server error: {str(e)}'
         }), 500
 
-# ============================================================================
-# API ENDPOINT: /api/parse  - LEX + SYNTAX ANALYSIS
-# Runs the lexer and (only if no lex errors) the LL(1) parser.
-# Short-circuits at the first failing stage and labels the response with
-# the failing stage so the IDE can highlight the right phase indicator.
-# ============================================================================
 @app.route('/api/parse', methods=['POST'])
 def parser_endpoint():
-    """
-    API endpoint for syntax analysis (parsing)
-    Expects JSON: {"source_code": "your GAL code here"}
-    Returns JSON: {"success": true/false, "tokens": [...], "errors": [...]}
-    """
     try:
         data = request.get_json()
         
@@ -194,10 +122,8 @@ def parser_endpoint():
         
         source_code = data['source_code']
         
-        # First, run the lexer to get tokens
         tokens, lex_errors = lex(source_code)
         
-        # Convert tokens to serializable format
         token_list = []
         for token in tokens:
             token_list.append({
@@ -208,7 +134,6 @@ def parser_endpoint():
                 'description': get_token_description(token.type, token.value)
             })
         
-        # Only run the parser if there are no lexical errors
         if lex_errors:
             return jsonify({
                 'success': False,
@@ -221,7 +146,6 @@ def parser_endpoint():
 
         parse_success, parse_errors = parser.parse(tokens)
         
-        # Determine which stages have errors
         stages = []
         if parse_errors:
             stages.append('syntax')
@@ -240,31 +164,16 @@ def parser_endpoint():
             'error': f'Server error: {str(e)}'
         }), 500
 
-# ============================================================================
-# API ENDPOINT: /api/health  - liveness check (used by deployment tools)
-# ============================================================================
 @app.route('/api/health', methods=['GET'])
 def health_check():
-    """Health check endpoint"""
     return jsonify({
         'status': 'healthy',
         'message': 'GAL Compiler Server is running'
     })
 
 
-# ============================================================================
-# API ENDPOINT: /api/semantic  - LEX + PARSE + AST + SEMANTIC ANALYSIS
-# Uses the parser's two-step API: parse_and_build (syntax + AST construction)
-# then validate_ast (tree-walking semantic checks). Distinguishes between
-# 'syntax' and 'semantic' error stages even though both come from the parser.
-# ============================================================================
 @app.route('/api/semantic', methods=['POST'])
 def semantic_endpoint():
-    """
-    API endpoint for semantic analysis
-    Expects JSON: {"source_code": "your GAL code here"}
-    Returns JSON: {"success": true/false, "errors": [...], "warnings": [...], "symbol_table": {...}}
-    """
     try:
         data = request.get_json()
         
@@ -275,10 +184,8 @@ def semantic_endpoint():
         
         source_code = data['source_code']
         
-        # First, run the lexer to get tokens
         tokens, lex_errors = lex(source_code)
         
-        # Convert tokens to serializable format
         token_list = []
         for token in tokens:
             token_list.append({
@@ -289,7 +196,6 @@ def semantic_endpoint():
                 'description': get_token_description(token.type, token.value)
             })
         
-        # If there are lexical errors, return them without semantic analysis
         if lex_errors:
             return jsonify({
                 'success': False,
@@ -299,12 +205,9 @@ def semantic_endpoint():
                 'stage': 'lexical'
             })
         
-        # Run the parser — validates syntax (LL1) then builds AST
         parse_result = parser.parse_and_build(tokens)
         
-        # If syntax or AST construction failed, return errors
         if not parse_result['success']:
-            # Distinguish semantic errors caught during AST building
             error_stage = parse_result.get('error_stage', 'syntax')
             return jsonify({
                 'success': False,
@@ -314,7 +217,6 @@ def semantic_endpoint():
                 'stage': error_stage
             })
         
-        # Run semantic analysis — tree-walking validation of the AST
         semantic_result = validate_ast(parse_result['ast'], parse_result['symbol_table'])
         
         return jsonify({
@@ -331,20 +233,8 @@ def semantic_endpoint():
             'error': f'Server error: {str(e)}'
         }), 500
 
-# ============================================================================
-# API ENDPOINT: /api/icg  - LEX + PARSE + SEMANTIC + ICG (display only)
-# ICG produces three-address code (TAC) for the IDE's "Intermediate Code"
-# tab. The interpreter does NOT consume this output; it walks the AST directly.
-# So ICG is a teaching/visualization layer, not a runtime layer.
-# ============================================================================
 @app.route('/api/icg', methods=['POST'])
 def icg_endpoint():
-    """
-    API endpoint for intermediate code generation.
-    Runs lexer → parser → semantic → ICG pipeline.
-    Expects JSON: {"source_code": "your GAL code here"}
-    Returns JSON with TAC instructions.
-    """
     try:
         data = request.get_json()
 
@@ -355,7 +245,6 @@ def icg_endpoint():
 
         source_code = data['source_code']
 
-        # 1. Lexical analysis
         tokens, lex_errors = lex(source_code)
 
         token_list = []
@@ -376,7 +265,6 @@ def icg_endpoint():
                 'stage': 'lexical'
             })
 
-        # 2. Syntax analysis + AST construction (parser builds AST)
         parse_result = parser.parse_and_build(tokens)
         if not parse_result['success']:
             error_stage = parse_result.get('error_stage', 'syntax')
@@ -387,7 +275,6 @@ def icg_endpoint():
                 'stage': error_stage
             })
 
-        # 3. Semantic analysis — tree-walking validation of the AST
         semantic_result = validate_ast(parse_result['ast'], parse_result['symbol_table'])
         if not semantic_result['success']:
             return jsonify({
@@ -398,7 +285,6 @@ def icg_endpoint():
                 'stage': 'semantic'
             })
 
-        # 4. Intermediate code generation
         icg_result = generate_icg(tokens)
 
         return jsonify({
@@ -417,44 +303,25 @@ def icg_endpoint():
         }), 500
 
 
-# ============================================================================
-# SYNCHRONOUS EXECUTION (no Socket.IO required)
-#
-# OutputCollector is an adapter — same .emit() interface as SessionEmitter,
-# but instead of streaming output via WebSocket it captures it in a list.
-# This is the adapter pattern: one Interpreter class, two delivery modes.
-# ============================================================================
-
 class OutputCollector:
-    """Drop-in replacement for SessionEmitter that collects output in a list."""
     def __init__(self):
-        self.outputs = []                 # Accumulated plant() output strings
-        self.needs_input = False          # Flips to True if program calls water()
+        self.outputs = []
+        self.needs_input = False
 
     def emit(self, event, data=None, **kwargs):
         if event == 'output' and data:
-            # Accumulate normal plant() output
             self.outputs.append(data.get('output', ''))
         elif event == 'input_required':
-            # No interactive channel here -> abort the interpreter so the
-            # client can switch to the Socket.IO flow that supports input.
             self.needs_input = True
             raise _InputNeeded()
 
 
 class _InputNeeded(Exception):
-    """Raised by OutputCollector to abort REST execution when water() is called."""
     pass
 
 
-# ============================================================================
-# API ENDPOINT: /api/run  - One-shot execution returning all output at once.
-# Used for non-interactive programs (no water() calls). For interactive runs,
-# the client uses the Socket.IO 'run_code' event below.
-# ============================================================================
 @app.route('/api/run', methods=['POST'])
 def run_endpoint():
-    """Run a GAL program synchronously and return all output."""
     try:
         data = request.get_json()
         if not data or 'source_code' not in data:
@@ -462,7 +329,6 @@ def run_endpoint():
 
         source_code = data['source_code']
 
-        # 1. Lex
         tokens, lex_errors = lex(source_code)
         if lex_errors:
             return jsonify({
@@ -472,7 +338,6 @@ def run_endpoint():
                 'errors': lex_errors
             })
 
-        # 2. Parse + build AST (parser builds the AST)
         parse_result = parser.parse_and_build(tokens)
         if not parse_result['success']:
             error_stage = parse_result.get('error_stage', 'syntax')
@@ -483,7 +348,6 @@ def run_endpoint():
                 'errors': [str(e) for e in parse_result['errors']]
             })
 
-        # 3. Semantic — tree-walking validation of the AST
         semantic_result = validate_ast(parse_result['ast'], parse_result['symbol_table'])
         if not semantic_result['success']:
             return jsonify({
@@ -495,7 +359,6 @@ def run_endpoint():
 
         ast = semantic_result['ast']
 
-        # 4. Interpret
         collector = OutputCollector()
         interp = Interpreter(socketio=collector)
         try:
@@ -507,7 +370,6 @@ def run_endpoint():
                 'errors': []
             })
         except _InputNeeded:
-            # Program called water() — return partial output and flag
             return jsonify({
                 'success': False,
                 'stage': 'execution',
@@ -536,35 +398,20 @@ def run_endpoint():
         return jsonify({'error': f'Server error: {str(e)}'}), 500
 
 
-# ============================================================================
-# SOCKET.IO INTERACTIVE EXECUTION
-#
-# This path supports water() input. The interpreter runs in a green thread
-# (eventlet) so it can park while waiting for input without blocking the
-# server. Output is streamed back via 'output' events as plant() fires.
-# ============================================================================
-
 @socketio.on('connect')
 def handle_connect():
-    # No setup needed — interpreter is created lazily on first 'run_code'.
     pass
 
 @socketio.on('disconnect')
 def handle_disconnect():
-    # Drop the user's interpreter so memory doesn't leak across reconnects.
     sid = request.sid
     interpreters.pop(sid, None)
 
 @socketio.on('run_code')
 def handle_run_code(data):
-    """
-    Run a GAL program through lex → parse → semantic → interpreter.
-    Program output is sent back via 'output' events.
-    """
     sid = request.sid
     source_code = data.get('source_code', '')
 
-    # 1. Lexical analysis
     tokens, lex_errors = lex(source_code)
     if lex_errors:
         for err in lex_errors:
@@ -572,10 +419,8 @@ def handle_run_code(data):
         emit('execution_complete', {'success': False, 'stage': 'lexical'})
         return
 
-    # Notify client that lexical analysis passed
     emit('stage_complete', {'stage': 'lexical', 'success': True})
 
-    # 2. Syntax analysis + AST construction (parser builds AST)
     parse_result = parser.parse_and_build(tokens)
     if not parse_result['success']:
         error_stage = parse_result.get('error_stage', 'syntax')
@@ -584,10 +429,8 @@ def handle_run_code(data):
         emit('execution_complete', {'success': False, 'stage': error_stage})
         return
 
-    # Notify client that syntax analysis passed
     emit('stage_complete', {'stage': 'syntax', 'success': True})
 
-    # 3. Semantic analysis — tree-walking validation of the AST
     semantic_result = validate_ast(parse_result['ast'], parse_result['symbol_table'])
     if not semantic_result['success']:
         for err in semantic_result['errors']:
@@ -595,23 +438,19 @@ def handle_run_code(data):
         emit('execution_complete', {'success': False, 'stage': 'semantic'})
         return
 
-    # Notify client that semantic analysis passed
     emit('stage_complete', {'stage': 'semantic', 'success': True})
 
     ast = semantic_result['ast']
 
-    # 4. Interpretation — run in background task for input support
-    # Cancel any previously-running interpreter for this session
     old_interp = interpreters.get(sid)
     if old_interp and hasattr(old_interp, '_cancelled'):
         old_interp._cancelled = True
-        # Unblock any pending wait_for_input so the old thread can exit
         for evt in list(old_interp.input_events.values()):
             try:
-                evt.send(None)   # eventlet.event.Event uses .send()
+                evt.send(None)
             except (AttributeError, AssertionError):
                 try:
-                    evt.set()    # threading.Event fallback
+                    evt.set()
                 except Exception:
                     pass
 
@@ -625,7 +464,7 @@ def handle_run_code(data):
             if not interp._cancelled:
                 socketio.emit('execution_complete', {'success': True, 'stage': 'execution'}, to=sid)
         except _CancelledError:
-            pass  # Old interpreter was cancelled by a new run — exit silently
+            pass
         except InterpreterError as e:
             if not getattr(interp, '_cancelled', False):
                 socketio.emit('output', {'output': f'Runtime Error: {e}'}, to=sid)
@@ -635,46 +474,28 @@ def handle_run_code(data):
                 socketio.emit('output', {'output': f'Internal Error: {e}'}, to=sid)
                 socketio.emit('execution_complete', {'success': False, 'stage': 'execution'}, to=sid)
         finally:
-            # Only remove ourselves — don't remove a newer interpreter
             if interpreters.get(sid) is interp:
                 interpreters.pop(sid, None)
 
     socketio.start_background_task(run_interpreter)
 
-# ============================================================================
-# SOCKET.IO INPUT CHANNEL - When a running program calls water(), the
-# interpreter parks on an event. The frontend prompts the user, sends back
-# 'capture_input', and this handler routes the value to the right interpreter.
-# ============================================================================
 @socketio.on('capture_input')
 def handle_capture_input(data):
-    """Receive input from the client and forward to the waiting interpreter."""
     sid = request.sid
     interp = interpreters.get(sid)
     if interp:
         var_name = data.get('var_name', '')
         input_value = data.get('input', '')
-        # Unblock the parked interpreter so execution resumes
         interp.provide_input(var_name, input_value)
 
 
-# ============================================================================
-# AI CHAT HELPER (Google Gemini)
-# Optional learning aid — answers user questions about GAL syntax. Falls
-# back to a rule-based reply if no GEMINI_API_KEY is set or the API fails.
-# This is NOT part of the compiler pipeline.
-# ============================================================================
-
-# Load the system prompt that teaches Gemini how to talk about GAL
 _prompt_path = os.path.join(os.path.dirname(__file__), 'ai', 'prompt.txt')
 with open(_prompt_path, 'r', encoding='utf-8') as _f:
     GAL_SYSTEM_PROMPT = _f.read()
 
 
-
-# Initialize Gemini client — requires GEMINI_API_KEY env var
 _gemini_client = None
-_chat_sessions = {}  # sid -> list of message dicts
+_chat_sessions = {}
 
 def _get_gemini_client():
     global _gemini_client
@@ -687,7 +508,6 @@ def _get_gemini_client():
 
 @app.route('/api/chat', methods=['POST'])
 def chat_endpoint():
-    """AI chat helper endpoint using Google Gemini."""
     try:
         data = request.get_json()
         if not data or 'message' not in data:
@@ -699,27 +519,22 @@ def chat_endpoint():
 
         client = _get_gemini_client()
         if client is None:
-            # No API key — use fallback
             fb_reply = fallback_reply(user_message)
             return jsonify({'reply': fb_reply, 'mode': 'fallback'})
 
-        # Build/get conversation history for this session
         if session_id not in _chat_sessions:
             _chat_sessions[session_id] = []
         history = _chat_sessions[session_id]
 
-        # Include editor code as context if provided
         full_message = user_message
         if editor_code.strip():
             full_message = f"[Current code in editor]:\n```\n{editor_code}\n```\n\nUser question: {user_message}"
 
         history.append({'role': 'user', 'parts': [{'text': full_message}]})
 
-        # Keep history manageable (last 20 messages)
         if len(history) > 20:
             history[:] = history[-20:]
 
-        # Try multiple models in case one has quota available
         models_to_try = ['gemini-2.5-flash', 'gemini-2.5-flash-lite', 'gemini-2.0-flash', 'gemini-2.0-flash-lite']
         last_error: Exception = RuntimeError("No Gemini models were available to try")
         for model_name in models_to_try:
@@ -733,16 +548,15 @@ def chat_endpoint():
                         max_output_tokens=4096,
                     ),
                 )
-                break  # success
+                break
             except Exception as model_err:
                 last_error = model_err
                 err_msg = str(model_err)
-                # Retry-worthy errors: quota, availability, or auth (same key fails for all models)
                 if '429' not in err_msg and 'RESOURCE_EXHAUSTED' not in err_msg and '503' not in err_msg and 'UNAVAILABLE' not in err_msg and '403' not in err_msg and 'PERMISSION_DENIED' not in err_msg:
-                    raise  # unexpected error, don't retry
+                    raise
                 continue
         else:
-            raise last_error  # all models failed
+            raise last_error
 
         reply = response.text or 'No response generated.'
 
@@ -751,30 +565,22 @@ def chat_endpoint():
         return jsonify({'reply': reply, 'mode': 'ai'})
 
     except Exception as e:
-        # All Gemini models failed — use rule-based fallback
         try:
             fb_reply = fallback_reply(user_message)
             return jsonify({'reply': fb_reply, 'mode': 'fallback'})
         except Exception:
-            pass  # fallback itself failed, return original error
+            pass
         err_str = str(e)
         return jsonify({'error': f'Chat error: {err_str}'}), 500
 
 @app.route('/api/chat/clear', methods=['POST'])
 def chat_clear_endpoint():
-    """Clear chat history for a session."""
     data = request.get_json() or {}
     session_id = data.get('session_id', 'default')
     _chat_sessions.pop(session_id, None)
     return jsonify({'success': True})
 
 
-# ============================================================================
-# SERVER STARTUP - Reads PORT/DEBUG env vars, prints a banner listing every
-# endpoint, then hands the app to eventlet's WSGI server.
-# host='0.0.0.0' makes the server reachable from any network interface,
-# not just localhost.
-# ============================================================================
 if __name__ == '__main__':
     port = int(os.environ.get('PORT', 5000))
     debug = os.environ.get('DEBUG', 'False') == 'True'
@@ -788,5 +594,4 @@ if __name__ == '__main__':
     print(f"  - POST http://localhost:{port}/api/icg (Intermediate Code Generation)")
     print(f"  - POST http://localhost:{port}/api/chat (AI Chat Helper)")
     print(f"  - Socket.IO: run_code (Execute Program)")
-    # allow_unsafe_werkzeug=True is needed when running inside eventlet during dev
     socketio.run(app, host='0.0.0.0', port=port, debug=debug, allow_unsafe_werkzeug=True)

Backend/shared/__init__.py

@@ -1,19 +1,3 @@
-# ============================================================================
-# SHARED PACKAGE - Cross-phase types used by every compiler stage
-# ============================================================================
-# Contains only the building blocks that genuinely cross phase boundaries:
-#   - tokens     : TT_* constants, Token class, get_token_description
-#                  (lexer creates, parser/semantic/icg/interpreter read)
-#   - ast_nodes  : AST node class hierarchy
-#                  (parser builds, semantic/icg/interpreter walk)
-#
-# Phase-private types live with their phase:
-#   - lexer/positions.py    : Position class (lexer-owned)
-#   - lexer/delimiters.py   : FSM character sets (lexer-only)
-#   - lexer/errors.py       : LexicalError
-#   - semantic/errors.py    : SemanticError
-#   - interpreter/errors.py : InterpreterError, ReturnValue, etc.
-# ============================================================================
 
 from .tokens import *  # noqa: F401,F403 - TT_* constants
 from .tokens import Token, get_token_description  # noqa: F401

Backend/shared/ast_nodes.py

@@ -1,36 +1,11 @@
-# ============================================================================
-# AST NODE CLASSES - The shape of every node in the GAL syntax tree
-# ============================================================================
-# Extracted from GALsemantic.py during the modular restructure.
-# Every compiler phase after parsing consumes these node types:
-#   - parser/builder.py constructs them
-#   - semantic/analyzer.py validates them
-#   - icg/generator.py walks them to emit TAC
-#   - interpreter/ evaluates them
-#
-# Named ast_nodes.py (not ast.py / not in an ast/ folder) so it does not
-# shadow Python's stdlib "ast" module — many third-party libraries
-# (flask, eventlet, werkzeug) call into stdlib ast and would break if
-# we hijacked the name.
-# ============================================================================
-
-
-# ============================================================================
-# AST NODE CLASSES
-# Each node has:
-#   - node_type   : a string label (e.g. "Program", "VariableDeclaration")
-#   - value       : the node's primary data (function name, operator, etc.)
-#   - children    : list of child ASTNodes
-#   - line        : source line for error reporting
-#   - parent      : back-pointer for traversals (set by add_child)
-# Subclasses below define convenient constructors for each AST shape.
-# ============================================================================
+
+
 class ASTNode:
     def __init__(self, node_type, value=None, line=None):
-        self.node_type = node_type  # Type of node (e.g., 'VariableDeclaration', 'BinaryOp')
-        self.value = value  # E.g. variable name, operator, etc.
-        self.children = []  # List of child nodes
-        self.parent = None  # Reference to parent node
+        self.node_type = node_type
+        self.value = value
+        self.children = []
+        self.parent = None
         self.line = line
 
     def add_child(self, child):
@@ -38,7 +13,6 @@ class ASTNode:
         self.children.append(child)
 
     def print_tree(self, level=0):
-        """Pretty-print the AST."""
         indent = ' ' * (level * 3)
         print(f"{indent}╚═{self.node_type}: {self.value if self.value else ''}")
         for child in self.children:
@@ -105,7 +79,6 @@ class WhileLoopNode(ASTNode):
 class DoWhileLoopNode(ASTNode):
     def __init__(self, condition, line=None):
         super().__init__("DoWhileLoop", line=line)
-        #self.add_child(condition)
 
 class PrintNode(ASTNode):
     def __init__(self, args, line=None):
@@ -217,18 +190,16 @@ class ListAccessNode(ASTNode):
 
 
 class MemberAccessNode(ASTNode):
-    """Represents bundle member access: p.age or p.addr.zip (nested)"""
     def __init__(self, object_name, member_name, line=None):
         super().__init__("MemberAccess", line=line)
         if isinstance(object_name, ASTNode):
-            self.add_child(object_name)  # Nested MemberAccessNode for chained access
+            self.add_child(object_name)
         else:
             self.add_child(ASTNode("Object", object_name, line=line))
         self.add_child(ASTNode("Member", member_name, line=line))
 
 
 class ArrayMemberAccessNode(ASTNode):
-    """Represents bundle array element member access: p[0].x"""
     def __init__(self, list_access_node, member_name, line=None):
         super().__init__("ArrayMemberAccess", line=line)
         self.add_child(list_access_node)
@@ -236,9 +207,8 @@ class ArrayMemberAccessNode(ASTNode):
 
 
 class BundleDefinitionNode(ASTNode):
-    """Represents a bundle (struct) type definition."""
     def __init__(self, bundle_name, members, line=None):
         super().__init__("BundleDefinition", line=line)
         self.bundle_name = bundle_name
-        self.members = members  # dict: {member_name: member_type}
+        self.members = members
 

Backend/shared/tokens.py

@@ -1,113 +1,100 @@
 
 
-# --- Reserved Words (Keywords) ---
-TT_RW_WATER       = 'water'     # Input function - reads user input
-TT_RW_PLANT       = 'plant'     # Output function - prints to console
-TT_RW_SEED        = 'seed'      # Data Type - integer (int)
-TT_RW_LEAF        = 'leaf'      # Data Type - character (char)
-TT_RW_BRANCH      = 'branch'    # Data Type - boolean (true/false)
-TT_RW_TREE        = 'tree'      # Data Type - double/float
-TT_RW_SPRING      = 'spring'    # Conditional statement - if
-TT_RW_WITHER      = 'wither'    # Conditional statement - else
-TT_RW_BUD         = 'bud'       # Conditional statement - else-if
-TT_RW_HARVEST     = 'harvest'   # Switch statement
-TT_RW_GROW        = 'grow'      # Loop - while
-TT_RW_CULTIVATE   = 'cultivate' # Loop - for
-TT_RW_TEND        = 'tend'      # Loop - do-while
-TT_RW_EMPTY       = 'empty'     # Void return type
-TT_RW_PRUNE       = 'prune'     # Break statement - exit loop
-TT_RW_SKIP        = 'skip'      # Continue statement - skip to next iteration
-TT_RW_RECLAIM     = 'reclaim'   # Return statement - return from function
-TT_RW_ROOT        = 'root'      # Main function entry point
-TT_RW_POLLINATE   = 'pollinate' # Function declaration
-TT_RW_VARIETY     = 'variety'   # Case label in switch statement
-TT_RW_FERTILE     = 'fertile'   # Constant declaration
-TT_RW_SOIL        = 'soil'      # Default case in switch statement
-TT_RW_BUNDLE      = 'bundle'    # Struct definition
-TT_RW_VINE        = 'vine'      # String data type
-
-# --- Operators & Symbols ---
-TT_IDENTIFIER = 'id'        # Variable/function names (e.g., myVar, calcTotal)
-TT_PLUS = '+'               # Addition operator
-TT_MINUS = '-'              # Subtraction operator
-TT_MUL = '*'                # Multiplication operator
-TT_DIV = '/'                # Division operator
-TT_MOD = '%'                # Modulo operator (remainder)
-TT_EXP = '**'               # Exponentiation operator (power)
-TT_EQ = '='                 # Assignment operator
-TT_EQTO = '=='              # Equality comparison operator
-TT_PLUSEQ = '+='            # Add and assign operator
-TT_MINUSEQ = '-='           # Subtract and assign operator
-TT_MULTIEQ = '*='           # Multiply and assign operator
-TT_DIVEQ = '/='             # Divide and assign operator
-TT_MODEQ = '%='             # Modulo and assign operator
-TT_EXPEQ = '**='            # Exponent and assign operator (x **= 2 → x = x ** 2)
-TT_CONCAT = '`'             # String concatenation operator
-TT_LPAREN = '('             # Left parenthesis
-TT_RPAREN = ')'             # Right parenthesis
-TT_SEMICOLON = ';'          # Statement terminator
-TT_COMMA = ','              # Separator (function args, array elements)
-TT_COLON = ':'              # Colon (used in switch cases)
-TT_BLOCK_START = '{'        # Block start (scope begin)
-TT_BLOCK_END = '}'          # Block end (scope close)
-TT_LT = '<'                 # Less than comparison
-TT_GT = '>'                 # Greater than comparison
-TT_LTEQ = '<='              # Less than or equal comparison
-TT_GTEQ = '>='              # Greater than or equal comparison
-TT_NOTEQ = '!='             # Not equal comparison
-TT_EOF = 'EOF'                  # End of file marker
-TT_AND = '&&'                   # Logical AND operator
-TT_OR = '||'                    # Logical OR operator
-TT_SINGLE_AND = '&'             # Invalid single ampersand
-TT_SINGLE_OR = '|'              # Invalid single pipe
-TT_NOT = '!'                    # Logical NOT operator
-TT_INCREMENT = '++'             # Increment operator (e.g., x++)
-TT_DECREMENT = '--'             # Decrement operator (e.g., x--)
-TT_LSQBR = '['                  # Left square bracket (array indexing)
-TT_RSQBR = ']'                  # Right square bracket
-TT_NEGATIVE = '~'               # Unary negation operator
-TT_MEMBER = 'member'            # Member token for struct access
-TT_INTEGERLIT = 'intlit'        # Integer literal token (e.g., 42, 100)
-TT_DOUBLELIT = 'dbllit'         # Double/float literal token (e.g., 3.14, 2.5)
-TT_STRINGLIT = 'stringlit'      # String literal token (e.g., "hello")
-TT_CHARLIT = 'chrlit'           # Character literal token (e.g., 'a')
-TT_BOOLLIT_TRUE = 'sunshine'    # Boolean true literal
-TT_BOOLLIT_FALSE = 'frost'      # Boolean false literal
-TT_STRCTACCESS = '.'            # Struct member access operator
-TT_NL = '\n'                    # Newline token
-TT_DOT = '.'                    # Dot operator (struct access)
-
-
-# ============================================================================
-# TOKEN CLASS - Represents a single token (lexeme)
-# ============================================================================
+TT_RW_WATER       = 'water'
+TT_RW_PLANT       = 'plant'
+TT_RW_SEED        = 'seed'
+TT_RW_LEAF        = 'leaf'
+TT_RW_BRANCH      = 'branch'
+TT_RW_TREE        = 'tree'
+TT_RW_SPRING      = 'spring'
+TT_RW_WITHER      = 'wither'
+TT_RW_BUD         = 'bud'
+TT_RW_HARVEST     = 'harvest'
+TT_RW_GROW        = 'grow'
+TT_RW_CULTIVATE   = 'cultivate'
+TT_RW_TEND        = 'tend'
+TT_RW_EMPTY       = 'empty'
+TT_RW_PRUNE       = 'prune'
+TT_RW_SKIP        = 'skip'
+TT_RW_RECLAIM     = 'reclaim'
+TT_RW_ROOT        = 'root'
+TT_RW_POLLINATE   = 'pollinate'
+TT_RW_VARIETY     = 'variety'
+TT_RW_FERTILE     = 'fertile'
+TT_RW_SOIL        = 'soil'
+TT_RW_BUNDLE      = 'bundle'
+TT_RW_VINE        = 'vine'
+
+TT_IDENTIFIER = 'id'
+TT_PLUS = '+'
+TT_MINUS = '-'
+TT_MUL = '*'
+TT_DIV = '/'
+TT_MOD = '%'
+TT_EXP = '**'
+TT_EQ = '='
+TT_EQTO = '=='
+TT_PLUSEQ = '+='
+TT_MINUSEQ = '-='
+TT_MULTIEQ = '*='
+TT_DIVEQ = '/='
+TT_MODEQ = '%='
+TT_EXPEQ = '**='
+TT_CONCAT = '`'
+TT_LPAREN = '('
+TT_RPAREN = ')'
+TT_SEMICOLON = ';'
+TT_COMMA = ','
+TT_COLON = ':'
+TT_BLOCK_START = '{'
+TT_BLOCK_END = '}'
+TT_LT = '<'
+TT_GT = '>'
+TT_LTEQ = '<='
+TT_GTEQ = '>='
+TT_NOTEQ = '!='
+TT_EOF = 'EOF'
+TT_AND = '&&'
+TT_OR = '||'
+TT_SINGLE_AND = '&'
+TT_SINGLE_OR = '|'
+TT_NOT = '!'
+TT_INCREMENT = '++'
+TT_DECREMENT = '--'
+TT_LSQBR = '['
+TT_RSQBR = ']'
+TT_NEGATIVE = '~'
+TT_MEMBER = 'member'
+TT_INTEGERLIT = 'intlit'
+TT_DOUBLELIT = 'dbllit'
+TT_STRINGLIT = 'stringlit'
+TT_CHARLIT = 'chrlit'
+TT_BOOLLIT_TRUE = 'sunshine'
+TT_BOOLLIT_FALSE = 'frost'
+TT_STRCTACCESS = '.'
+TT_NL = '\n'
+TT_DOT = '.'
+
+
 class Token:
-    """Represents a token with type, value, line number, and column number"""
 
     def __init__(self, type_, value=None, line=1, col=0):
-        self.type = type_    # Token type (e.g., TT_IDENTIFIER, TT_INTEGERLIT)
-        self.value = value   # Token text/value (e.g., "myVar", "42")
-        self.line = line     # Line number where token appears
-        self.col = col       # Column number where token starts (0-based)
+        self.type = type_
+        self.value = value
+        self.line = line
+        self.col = col
 
 
-# ============================================================================
-# TOKEN TYPE DESCRIPTIONS - Maps token types to human-readable descriptions
-# ============================================================================
 def get_token_description(token_type: str, value: str = '') -> str:
-    """Returns a descriptive name for each token type"""
-    # Handle negative literals: value starts with ~ but token type is intlit/dbllit
     if token_type == 'intlit' and isinstance(value, str) and value.startswith('~'):
         return 'negative integer'
     if token_type == 'dbllit' and isinstance(value, str) and value.startswith('~'):
         return 'negative float'
 
     descriptions = {
-        # Reserved Words - I/O
         'water': 'Input Function',
         'plant': 'Output Function',
 
-        # Reserved Words - Data Types
         'seed': 'Integer Type',
         'leaf': 'Character Type',
         'branch': 't/f',
@@ -115,7 +102,6 @@ def get_token_description(token_type: str, value: str = '') -> str:
         'vine': 'String Type',
         'empty': 'Void Type',
 
-        # Reserved Words - Control Flow
         'spring': 'If Statement',
         'wither': 'Else Statement',
         'bud': 'Else-If Statement',
@@ -123,23 +109,19 @@ def get_token_description(token_type: str, value: str = '') -> str:
         'variety': 'Case Label',
         'soil': 'Default Case',
 
-        # Reserved Words - Loops
         'grow': 'While Loop',
         'cultivate': 'For Loop',
         'tend': 'Do-While Loop',
         'prune': 'Break Statement',
         'skip': 'Continue Statement',
 
-        # Reserved Words - Functions
         'root': 'Main Function',
         'pollinate': 'Function Declaration',
         'reclaim': 'Return Statement',
 
-        # Reserved Words - Other
         'fertile': 'Constant Declaration',
         'bundle': 'Struct Definition',
 
-        # Identifiers and Literals
         'id': 'Identifier',
         'intlit': 'Integer Literal',
         'dbllit': 'double Literal',
@@ -148,7 +130,6 @@ def get_token_description(token_type: str, value: str = '') -> str:
         'sunshine': 'Boolean True',
         'frost': 'Boolean False',
 
-        # Arithmetic Operators
         '+': 'Plus Operator',
         '-': 'Minus Operator',
         '*': 'Multiply Operator',
@@ -159,7 +140,6 @@ def get_token_description(token_type: str, value: str = '') -> str:
         '++': 'Increment Operator',
         '--': 'Decrement Operator',
 
-        # Assignment Operators
         '=': 'Assign Operator',
         '+=': 'Add-Assign Operator',
         '-=': 'Sub-Assign Operator',
@@ -167,7 +147,6 @@ def get_token_description(token_type: str, value: str = '') -> str:
         '/=': 'Div-Assign Operator',
         '%=': 'Mod-Assign Operator',
 
-        # Comparison Operators
         '==': 'Equal Operator',
         '!=': 'Not-Equal Operator',
         '<': 'Less-Than Operator',
@@ -175,14 +154,12 @@ def get_token_description(token_type: str, value: str = '') -> str:
         '<=': 'Less-Equal Operator',
         '>=': 'Greater-Equal Operator',
 
-        # Logical Operators
         '&&': 'AND Operator',
         '&': 'Invalid Single-Ampersand',
         '||': 'OR Operator',
         '|': 'Invalid Single-Pipe',
         '!': 'NOT Operator',
 
-        # Delimiters and Punctuation
         '(': 'Left Parenthesis',
         ')': 'Right Parenthesis',
         '{': 'Left Brace',
@@ -195,7 +172,6 @@ def get_token_description(token_type: str, value: str = '') -> str:
         '.': 'Dot Operator',
         '`': 'Concatenation Operator',
 
-        # Special
         'member': 'Struct Member',
         'EOF': 'End of File',
         '\n': 'Newline'

UI/main.js

@@ -54,7 +54,6 @@
                   [/\b(bloom|wither|spring)\b/, "io"],
                   // Comments
                   [/\/\/.*/, "comment"],
-                  [/#.*/, "comment"],
                   [/\/\*/, 'comment', '@comment'],
                   // Numbers (integers and decimals)
                   [/\d+\.\d+/, "number"],
@@ -213,7 +212,6 @@
               // Start of comment
               if (ch === '/' && next === '/') { inLineComment = true; col++; continue; }
               if (ch === '/' && next === '*') { inBlockComment = true; i++; col += 2; continue; }
-              if (ch === '#') { inLineComment = true; col++; continue; }
               // Start of string/char
               if (ch === '"') { inString = true; col++; continue; }
               if (ch === "'") { inChar = true; col++; continue; }
@@ -268,7 +266,7 @@
                 continue;
               }
               // Skip empty lines, line comments, and brace-only lines
-              if (!trimmed || trimmed.startsWith('//') || trimmed.startsWith('#')) continue;
+              if (!trimmed || trimmed.startsWith('//')) continue;
               // Strip inline comments to get actual code
               const codePart = trimmed.replace(/\/\/.*$/, '').trimEnd();
               if (!codePart) continue;