GSoC/DMP 2025 Week 4-5: feat(runtime): Add Symbol Table

[sa-fw-an]

This PR implements the complete Symbol Table Module for the Music Blocks 4 Program Engine, as outlined in Weeks 4-5 of the GSoC project.

What's Implemented

Core Symbol Table Architecture

• Multi-level scope-aware symbol table supporting global, function, block, and parameter scopes
• Shadowing and scope resolution with correct precedence for symbol lookup (current → parent → global)
• Symbol metadata management (type, mutability, scope, data type, custom info)
• Support for variable, function, iterator, and parameter symbols
• Error handling for redeclaration, unknown symbol access, and invalid scope operations

Symbol Table and Related Classes

• SymbolTable: Core manager for symbol declarations, lookups, and scope stack
• SymbolEntry: Immutable metadata representation for each symbol (variable/function)
• SymbolResolver: Resolves symbol names to memory locations and metadata, integrates with memory module
• SymbolManager: Orchestrates symbol table and memory operations in sync
• Comprehensive type system for symbol kinds, data types, and scopes

Operations and Features

• Symbol Declaration: Controlled addition of variables, functions, parameters with type and mutability
• Symbol Lookup: Resolution across nested scopes with shadowing and parent fallback
• Scope Management: pushScope(), popScope() for entering/exiting lexical scopes
• Symbol Removal and Reset: Remove individual symbols or clear/reset scopes as needed
• Custom Metadata: Attach arbitrary metadata (e.g., source location, initialization state, return types)

How to Test

Run Tests

npm run test
# or for individual file 
npm run test sample/symbol-table.test.ts

Weeks 4-5 Objectives - COMPLETED

As discussed in Weeks 4-5:

1. ✅ Symbol Table Core: Declaration, lookup, shadowing, and scope stack management
2. ✅ SymbolEntry Metadata: Immutable, deeply frozen metadata on all symbol entries
3. ✅ Scope Operations: Support for global, function, block, and parameter scopes
4. ✅ Error Handling: User-friendly errors for redeclaration, missing symbols, and scope misuse
5. ✅ Integration: SymbolResolver and SymbolManager tightly integrated with memory module
6. ✅ Comprehensive Tests: Unit and advanced tests for all supported operations

Symbol Table API

• SymbolTable: declare(), lookup(), pushScope(), popScope(), removeSymbol(), clearCurrentScope(), reset()
• SymbolEntry: Immutable symbol metadata (name, type, scope, mutability, metadata, etc.)
• SymbolResolver/SymbolManager: Bridge between symbol table and memory system