Project Architecture Rules (Non-Obvious Only)

Language Documentation

For comprehensive language specifications, syntax, and features, refer to the edu.wiki documentation:

• Basic Syntax: edu.wiki/Basic-Syntax.md - Core language syntax, types, functions, classes
• Feature Specification: edu.wiki/Feature-Specification.md - Detailed feature requirements and implementation specs
• EBNF Grammar: edu.wiki/EBNF-Grammar.md - Formal language grammar definition
• Project Goals: edu.wiki/Goals.md - High-level language design goals and philosophy

Critical Design Principle

NO HARDCODED IMPLEMENTATIONS: Parser and interpreter must not contain hardcoded function definitions, imports, or language features unless they are core edu language constructs. All user-defined functions, imports, and modules must be processed dynamically through the AST and module system.

Architecture Constraints

• Direct AST interpretation bypasses traditional compile-transpile cycle for 110x speed improvement
• Three-phase execution: Phase 1 (imports) → Phase 2 (declarations) → Phase 3 (statements)
• Module system uses shared function body references to enable safe import/export without AST corruption
• Environment hierarchy: globals → module environments → function execution environments
• Function memory model: importedFunction pointer preserves original while wrapper handles module context
• Token classification system: Declaration vs Keyword types determine parser routing logic
• Const enforcement: separate constFlags map in Environment rather than Value-level immutability
• Module registry pattern: gModuleRegistry.executeFunction() prevents interpreter recursion cycles
• Test auto-discovery: SCons scans __tests__/ directories eliminating manual test registration
• Platform abstraction: SCons handles MSVC/GCC compiler differences while maintaining C++17 standard