ci: Bump actions/checkout from 4 to 5

.github/workflows/ci.yml

@@ -17,7 +17,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Setup Node.js ${{ matrix.node-version }}
         uses: actions/setup-node@v4
@@ -76,7 +76,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Setup Node.js
         uses: actions/setup-node@v4
@@ -112,7 +112,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Setup Node.js
         uses: actions/setup-node@v4
@@ -150,7 +150,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Setup Node.js
         uses: actions/setup-node@v4
@@ -191,7 +191,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           fetch-depth: 0
 

.github/workflows/claude.yml

@@ -26,7 +26,7 @@ jobs:
       actions: read # Required for Claude to read CI results on PRs
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           fetch-depth: 1
 

.github/workflows/docs.yml

@@ -26,7 +26,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Setup Node.js
         uses: actions/setup-node@v4

.github/workflows/pr-check.yml

@@ -55,7 +55,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Setup Node.js
         uses: actions/setup-node@v4

.github/workflows/release.yml

@@ -32,7 +32,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           fetch-depth: 0
           token: ${{ secrets.GITHUB_TOKEN }}

CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] - 2024-12-26
+
+### Added
+- Comprehensive Metadata API for compilation and execution analysis
+  - Token and AST node tracking with statistics
+  - Module resolution and dependency graph generation
+  - Function call and variable access profiling
+  - Control flow and pipeline operation tracking
+  - Live execution state and path recording
+  - Export capability for external tools
+- MetadataCollector class for easy integration with interpreter
+- Query methods for hot functions, hot variables, and execution insights
+- Full test suite for metadata API (43 tests)
+
+### Changed
+- Updated documentation to include Metadata API usage examples
+- Enhanced README with metadata feature highlights
+
 ## [0.1.0] - 2024-01-25
 
 ### Added

README.md

@@ -21,6 +21,7 @@ A CSP-safe workflow programming language for browser automation, designed to run
 - ✨ **Full Class Support** - Classes with constructors, methods, **inheritance with super()**, and proper `this` binding
 - 🔒 **Robust Variable Scoping** - Const immutability, var hoisting, block scoping with proper shadowing
 - ♻️ **Circular Dependency Support** - Handles circular module imports without memory leaks
+- 📊 **Execution Metadata API** - Comprehensive compilation and runtime metadata for debugging and analysis
 - 🧪 **Fully Tested** - Comprehensive test suite using Vitest (90/90 tests passing - 100% coverage)
 
 ## Installation
@@ -280,6 +281,47 @@ await interpreter.execute(`
 `);
 ```
 
+## Metadata API
+
+Wang provides a comprehensive metadata API that captures and exposes compilation, interpretation, and execution data:
+
+```javascript
+import { WangInterpreter } from 'wang-lang';
+import { MetadataCollector } from 'wang-lang/metadata';
+
+// Create interpreter with metadata collection
+const collector = new MetadataCollector();
+const interpreter = new WangInterpreter({
+  onNodeVisit: (node, depth) => collector.onNodeVisit(node, depth),
+  onFunctionCall: (name, args, node) => collector.onFunctionCall(name, args, node),
+  onVariableAccess: (name, type, value) => collector.onVariableAccess(name, type, value)
+});
+
+// Execute code with metadata collection
+collector.onExecutionStart();
+await interpreter.execute(code);
+collector.onExecutionEnd();
+
+// Get comprehensive metadata
+const metadata = collector.getMetadata();
+
+// Query execution insights
+console.log('Hot functions:', metadata.getHotFunctions(5));
+console.log('Variable access patterns:', metadata.getHotVariables(5));
+console.log('Execution path:', metadata.getExecutionPath());
+console.log('Performance summary:', metadata.getExecutionSummary());
+
+// Export for external tools
+const json = collector.export();
+```
+
+### Metadata Categories
+
+- **Compilation Phase**: Tokens, AST nodes, parse timing, source mapping
+- **Interpretation Phase**: Module resolution, symbol tables, dependency graphs
+- **Execution Phase**: Call tracking, variable access, control flow, pipeline operations
+- **Runtime Data**: Live variables, execution path, current position, event stream
+
 ## Language Support
 
 ### ✅ Fully Supported Features

WANG_LANGUAGE_REFERENCE.md

@@ -1018,6 +1018,99 @@ const promises = items.map(item => processAsync(item));
 const results = await Promise.all(promises);
 ```
 
+## Metadata API
+
+Wang provides comprehensive metadata collection for debugging and analysis:
+
+### Basic Usage
+```javascript
+import { WangInterpreter } from 'wang-lang';
+import { MetadataCollector, WangMetadata } from 'wang-lang/metadata';
+
+// Create metadata collector
+const collector = new MetadataCollector();
+
+// Hook into interpreter
+const interpreter = new WangInterpreter({
+  onNodeVisit: (node, depth) => collector.onNodeVisit(node, depth),
+  onFunctionCall: (name, args, node) => collector.onFunctionCall(name, args, node),
+  onVariableAccess: (name, type, value) => collector.onVariableAccess(name, type, value),
+  onModuleResolve: (from, requested, resolved) => collector.onModuleResolve(from, requested, resolved),
+  onBranch: (type, condition, result, node) => collector.onBranch(type, condition, result, node),
+  onPipeline: (operator, input, output, node) => collector.onPipeline(operator, input, output, node),
+  onError: (error, node) => collector.onError(error, node)
+});
+
+// Execute with metadata collection
+collector.onExecutionStart();
+await interpreter.execute(code);
+collector.onExecutionEnd();
+
+// Query metadata
+const metadata = collector.getMetadata();
+```
+
+### Available Metadata
+
+#### Compilation Phase
+- Token stream with types and counts
+- AST/CST node statistics and depth
+- Parse timing and errors
+- Source location mapping
+
+#### Interpretation Phase
+- Module resolution tracking (success/failure)
+- Symbol tables (variables, functions, classes)
+- Import/export dependencies
+- Scope chain information
+
+#### Execution Phase
+- Function call tracking with stack depth
+- Variable read/write access patterns
+- Control flow branches taken
+- Pipeline operation transformations
+- Loop iteration counts
+- Error tracking with context
+
+#### Runtime Data
+- Current execution position (line/column)
+- Live variable values
+- Execution path history
+- Event stream with timestamps
+
+### Query Methods
+
+```javascript
+// Performance analysis
+const hotFunctions = metadata.getHotFunctions(10);      // Top 10 most called functions
+const hotVariables = metadata.getHotVariables(10);      // Top 10 most accessed variables
+
+// Execution insights
+const executionPath = metadata.getExecutionPath(100);   // Last 100 lines executed
+const callStack = metadata.getCallStack();              // Current call stack
+const currentState = metadata.getCurrentState();        // Current position and variables
+
+// Summaries
+const compilationSummary = metadata.getCompilationSummary();
+const interpretationSummary = metadata.getInterpretationSummary();
+const executionSummary = metadata.getExecutionSummary();
+
+// Dependency analysis
+const depGraph = metadata.getDependencyGraph();         // Module dependency graph
+
+// Export for external tools
+const json = collector.export();                        // Full metadata as JSON
+```
+
+### Use Cases
+
+1. **Performance Profiling**: Identify hot functions and bottlenecks
+2. **Debugging**: Track execution flow and variable changes
+3. **Code Coverage**: Analyze which code paths are executed
+4. **Dependency Analysis**: Understand module relationships
+5. **Error Diagnosis**: Get full context when errors occur
+6. **Development Tools**: Build custom debuggers and profilers
+
 ---
 
 *This document covers Wang Language v1.0.0 with 100% test coverage (90/90 tests passing). For implementation details, see source code and test suite.*