GSoC/DMP 2025 Week 1: feat(program): Add Abstract classes

[sa-fw-an]

This PR implements the complete Abstract Syntax Tree (AST) framework for Music Blocks 4 Program Engine as discussed in Week 1 of the GSoC project. The implementation provides a comprehensive type-safe foundation for representing, constructing, and manipulating Music Blocks programs
The work initally was started on replit.

What's Implemented

Core AST Architecture

• Complete inheritance hierarchy with proper TypeScript typing
• ASTNodeBase as root class (only class with "Base" suffix following naming conventions)
• Abstract base classes for all major AST categories (Program, Block, Statement, Expression, etc.)
• Immutable properties with getter/setter patterns for encapsulation
• Type safety with runtime type identification for all nodes

Expression System

• Literal Expressions: NumericLiteralExpression, StringLiteralExpression, BooleanLiteralExpression
• Operator Expressions: UnaryOperatorExpression, BinaryOperatorExpression with comprehensive operator support
• Complex Expressions: FunctionCallExpression, MemberExpression, ArrayExpression, DictExpression
• Identifier System: IdentifierExpression for variable/function references

Statement Framework

• Simple Statements: Variable declarations/assignments, function calls, jump statements
• Compound Statements: Context statements, branch/conditional logic, loops, sequence operations
• Control Flow: If-then-else branches, pattern matching, iteration/condition loops
• Context Management: Modifying and declarative context statements for Music Blocks semantics

Function & Program Structure

• Program Declaration: Top-level container for function declarations
• Thread Functions: Auto-executed entry points (e.g., "Start" blocks)
• Custom Functions: User-defined reusable functions with parameters
• Block System: Statement containers with proper scope management

Testing Implementation

Test Suite Structure

Located in src/sample/:

1. Basic Functionality Tests (simple-test.ts)

   • Tests fundamental AST node creation and property access
   • Verifies inheritance hierarchy and type system
   • Validates getter/setter patterns

2. Program Construction Tests (program-test.ts)

   • Tests complete Music Blocks program assembly
   • Validates nested structures and complex relationships

3. AST Structure Tests (astTest.ts)

   • Comprehensive AST tree visualization
   • Node counting and statistics
   • Type distribution analysis

How to Test

Run Tests

ts-node sample/program-test.ts

Expected Output

• All AST nodes create successfully with proper types
• Program statistics show correct node counts and relationships
• JSON serialization works for debugging and inspection
• Complex nested structures build without errors

Week 1 Objectives - COMPLETED

As discussed in Week 1:

1. ✅ Technical Specification: Complete AST hierarchy defined with proper inheritance
2. ✅ Class Interfaces: All abstract base classes implemented with correct relationships
3. ✅ Concrete Classes: All Music Blocks constructs implemented as concrete classes
4. ✅ AST Building Examples: Real program construction demonstrated step-by-step
5. ✅ Inheritance Validation: Proper parent-child relationships following mentor guidance

This PR establishes the complete AST framework foundation for Music Blocks 4, enabling all subsequent development phases of the program engine.

[sa-fw-an]

@meganindya Please have a look