hakorune/docs/private/roadmap/phases/phase-19-enum-match/ARCHITECTURE_SUMMARY.md

@enum Architecture Summary (Quick Reference)

For: Developers who want the TL;DR version See Also: enum-module-architecture.md (complete design)

---

File Map (What Goes Where)

┌─────────────────────────────────────────────────────────────────┐
│                       @enum Implementation                      │
│                        File Organization                        │
└─────────────────────────────────────────────────────────────────┘

📁 src/
├── 📄 ast.rs                                    [MODIFY +80 lines]
│   └── Add: EnumDeclaration, EnumVariant, EnumField structs
│
├── 📁 parser/
│   ├── 📄 mod.rs                                [MODIFY +10 lines]
│   │   └── Integrate enum parsing in parse_statement()
│   └── 📁 declarations/
│       ├── 📄 mod.rs                            [MODIFY +1 line]
│       │   └── Export enum_parser module
│       └── 📄 enum_parser.rs                    [NEW ~200 lines] ⭐
│           └── parse_enum_declaration()
│
└── 📁 macro/
    ├── 📄 mod.rs                                [MODIFY +1 line]
    │   └── Export enum_expander module
    ├── 📄 engine.rs                             [MODIFY +15 lines]
    │   └── Call enum_expander::expand_enum()
    └── 📄 enum_expander.rs                      [NEW ~300 lines] ⭐
        ├── expand_enum()
        ├── generate_box_declaration()
        └── generate_static_box()

📁 apps/
└── 📁 tests/
    └── 📁 enum/                                 [NEW directory] ⭐
        ├── 📄 test_enum_basic.hako             [NEW ~40 lines]
        ├── 📄 test_enum_option.hako            [NEW ~30 lines]
        └── 📄 test_enum_multi.hako             [NEW ~50 lines]

📁 docs/
├── 📁 reference/language/
│   └── 📄 enum-syntax.md                        [NEW ~300 lines] ⭐
│       └── User guide for @enum
└── 📁 development/roadmap/phases/phase-19-enum-match/
    ├── 📄 enum-module-architecture.md           [THIS DOC] ⭐
    ├── 📄 IMPLEMENTATION_CHECKLIST.md           [CHECKLIST] ⭐
    └── 📄 enum-implementation-notes.md          [NEW ~200 lines] ⭐
        └── Developer implementation notes

---

Data Flow (Pipeline)

┌──────────────────────────────────────────────────────────────────────┐
│                     @enum Processing Pipeline                        │
└──────────────────────────────────────────────────────────────────────┘

Source Code:
  @enum Result { Ok(value: T), Err(error: E) }
         │
         ▼
  ┌─────────────────┐
  │   Tokenizer     │  (existing)
  └─────────────────┘
         │ Token Stream: [@, enum, Result, {, Ok, (, value, :, T, ), ...]
         ▼
  ┌─────────────────┐
  │  Parser         │  src/parser/declarations/enum_parser.rs (NEW)
  │  enum_parser.rs │  ← parse_enum_declaration()
  └─────────────────┘
         │ EnumDeclaration AST
         ▼
  ┌─────────────────┐
  │  AST Structs    │  src/ast.rs (MODIFY)
  │  ast.rs         │  ← EnumDeclaration, EnumVariant, EnumField
  └─────────────────┘
         │ EnumDeclaration AST
         ▼
  ┌─────────────────┐
  │  Macro Engine   │  src/macro/engine.rs (MODIFY)
  │  engine.rs      │  ← Call enum_expander::expand_enum()
  └─────────────────┘
         │
         ▼
  ┌─────────────────┐
  │  Enum Expander  │  src/macro/enum_expander.rs (NEW)
  │ enum_expander.rs│  ← expand_enum()
  └─────────────────┘
         │ Vec<ASTNode> [BoxDeclaration, StaticBoxDeclaration]
         ▼
  ┌─────────────────────────────────────────────────────────────────┐
  │  Generated AST:                                                 │
  │                                                                 │
  │  box ResultBox<T, E> {                                          │
  │    variant: StringBox                                           │
  │    ok_value: T                                                  │
  │    err_error: E                                                 │
  │    birth(variant, ok_value, err_error) { ... }                  │
  │    is_ok() { return me.variant == "Ok" }                        │
  │    is_err() { return me.variant == "Err" }                      │
  │  }                                                              │
  │                                                                 │
  │  static box Result {                                            │
  │    Ok(value) { return new ResultBox("Ok", value, null) }        │
  │    Err(error) { return new ResultBox("Err", null, error) }      │
  │  }                                                              │
  └─────────────────────────────────────────────────────────────────┘
         │ BoxDeclaration + StaticBoxDeclaration AST
         ▼
  ┌─────────────────┐
  │  MIR Builder    │  (existing)
  └─────────────────┘
         │ MIR
         ▼
  ┌─────────────────┐
  │  Backend        │  (existing)
  │  VM/LLVM/WASM   │
  └─────────────────┘
         │
         ▼
     Executable

---

Module Dependencies (No Cycles)

┌─────────────────────────────────────────────────────────────┐
│                  Dependency Graph                           │
│                  (Linear Flow)                              │
└─────────────────────────────────────────────────────────────┘

tokenizer.rs
    ↓
enum_parser.rs ──depends on──> ast.rs (EnumDeclaration structs)
    ↓
ast.rs
    ↓
enum_expander.rs ──depends on──> ast.rs (BoxDeclaration structs)
    ↓
engine.rs ──depends on──> enum_expander.rs
    ↓
parser/mod.rs (integration)
    ↓
MIR builder (existing)

✅ No circular dependencies
✅ Clear data flow
✅ Easy to test each layer independently

---

Naming Conventions (Quick Reference)

Item	Pattern	Example
Files	snake_case.rs	enum_parser.rs, enum_expander.rs
AST structs	CamelCase	EnumDeclaration, EnumVariant, EnumField
Functions	verb_noun()	parse_enum_declaration(), expand_enum()
Tests	test_*.hako	test_enum_basic.hako
Input syntax	@enum Name	@enum Result, @enum Option
Generated box	{Name}Box<T>	ResultBox<T, E>, OptionBox<T>
Generated static	{Name}	Result, Option
Variant fields	{variant}_{field}	ok_value, err_error
Query methods	is_{variant}()	is_ok(), is_err()

---

Test Organization (3 Layers)

┌─────────────────────────────────────────────────────────────────┐
│                     Test Strategy                               │
└─────────────────────────────────────────────────────────────────┘

Layer 1: Parser Unit Tests (Rust)
  📁 src/parser/declarations/enum_parser.rs
  └── #[cfg(test)] mod tests {
      ✓ test_parse_two_variant_enum()
      ✓ test_parse_zero_field_variant()
      ✓ test_duplicate_variant_error()
  }

  Run: cargo test --lib enum_parser::tests

Layer 2: Expander Unit Tests (Rust)
  📁 src/macro/enum_expander.rs
  └── #[cfg(test)] mod tests {
      ✓ test_expand_result_enum()
      ✓ test_generated_box_fields()
      ✓ test_generated_is_methods()
  }

  Run: cargo test --lib enum_expander::tests

Layer 3: Integration Tests (Hakorune)
  📁 apps/tests/enum/
  ├── test_enum_basic.hako       ← Result-like (Ok/Err)
  ├── test_enum_option.hako      ← Option-like (Some/None)
  └── test_enum_multi.hako       ← 3+ variants

  Run: ./target/release/hako apps/tests/enum/*.hako

---

Timeline (3 Days + 1 Buffer)

┌─────────────────────────────────────────────────────────────────┐
│                     Implementation Timeline                     │
└─────────────────────────────────────────────────────────────────┘

Day 1: Parser + AST (Foundation)                    ⏰ 8 hours
  ✓ Add AST structs (EnumDeclaration, EnumVariant, EnumField)
  ✓ Create enum_parser.rs
  ✓ Implement parse_enum_declaration()
  ✓ Add tokenizer support for @enum
  ✓ Write parser unit tests
  ✓ Integration: Export from mod.rs

  Output: Can parse @enum syntax into AST ✅

Day 2: Macro Expander (Code Generation)             ⏰ 8 hours
  ✓ Create enum_expander.rs
  ✓ Implement expand_enum()
  ✓ Implement generate_box_declaration()
  ✓ Implement generate_static_box()
  ✓ Write expander unit tests
  ✓ Integration: Call from engine.rs

  Output: Can transform enum AST → box AST ✅

Day 3: Integration Tests + Documentation            ⏰ 8 hours
  ✓ Create apps/tests/enum/ directory
  ✓ Write test_enum_basic.hako (Result-like)
  ✓ Write test_enum_option.hako (Option-like)
  ✓ Write test_enum_multi.hako (3+ variants)
  ✓ Write enum-syntax.md (user guide)
  ✓ Write enum-implementation-notes.md (dev notes)

  Output: Full pipeline working + documented ✅

Day 4: Polish + Edge Cases (Buffer)                 ⏰ 4-8 hours
  ✓ Error handling (duplicate variants, invalid names)
  ✓ Edge cases (zero-field variants, single variant)
  ✓ Code review and refactoring
  ✓ Clippy and fmt fixes

  Output: Production-ready code ✅

---

Success Criteria (Checklist)

• ✅ Parser: Can parse @enum Result { Ok(value: T), Err(error: E) }
• ✅ AST: EnumDeclaration nodes correctly constructed
• ✅ Expander: Generates BoxDeclaration + StaticBoxDeclaration
• ✅ Generated Code: Valid Hakorune syntax
• ✅ Tests: All integration tests pass
• ✅ Docs: User guide and developer notes complete
• ✅ Errors: Helpful error messages for common mistakes
• ✅ Edge Cases: Zero-field variants, single variant, many variants
• ✅ No Regressions: Existing tests still pass

---

Quick Commands (Copy-Paste Ready)

# Day 1: Build and test parser
cargo build
cargo test --lib enum_parser::tests

# Day 2: Build and test expander
cargo build
cargo test --lib enum_expander::tests

# Day 3: Run integration tests
./target/release/hako apps/tests/enum/test_enum_basic.hako
./target/release/hako apps/tests/enum/test_enum_option.hako
./target/release/hako apps/tests/enum/test_enum_multi.hako

# Day 4: Code quality checks
cargo clippy
cargo fmt
cargo test

# All enum tests at once
for test in apps/tests/enum/*.hako; do
    echo "Running $test..."
    ./target/release/hako "$test" || echo "FAILED: $test"
done

---

Key Design Principles

1. Separation of Concerns: Parser → AST → Expander → Engine (clear boundaries)
2. Testability: 3-layer testing (parser unit, expander unit, integration)
3. Follows Existing Patterns: Consistent with box_definition.rs style
4. Minimal Changes: Only 5 files modified + 8 files created
5. Future-Proof: Easy to extend for match expressions (Phase 19.2)

---

FAQ (Quick Answers)

Q: Where do I start? A: Read IMPLEMENTATION_CHECKLIST.md and start Day 1

Q: What if I get stuck? A: Check enum-module-architecture.md for detailed design

Q: How do I run tests? A: See "Quick Commands" section above

Q: What about match expressions? A: Phase 19.2 (future work) - hooks are in place for easy integration

Q: Will this break existing code? A: No - all changes are additive, no existing functionality modified

Q: How do I generate documentation? A: cargo doc --open for Rust docs, markdown files for user docs

---

Next Steps

1. ✅ Review this summary
2. ✅ Read IMPLEMENTATION_CHECKLIST.md
3. ✅ Start Day 1: Parser + AST
4. ✅ Follow checklist day by day
5. ✅ Celebrate when done! 🎉

---

Document Version: 1.0 Last Updated: 2025-10-08 Status: Ready for Implementation ✅