Run Scala interpreter in the browser

Author: nightscape

BROWSER_COMPILER_DESIGN.md

@@ -0,0 +1,99 @@
+# GitHub Actions workflow to build and deploy the browser compiler demo to GitHub Pages
+
+name: Deploy Demo to GitHub Pages
+
+on:
+  push:
+    branches: [main, master]
+    paths:
+      - 'browser-interpreter/**'
+  pull_request:
+    branches: [main, master]
+    paths:
+      - 'browser-interpreter/**'
+  workflow_dispatch:  # Allow manual trigger from any branch
+    inputs:
+      deploy:
+        description: 'Deploy to GitHub Pages'
+        required: false
+        default: true
+        type: boolean
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Java
+        uses: actions/setup-java@v4
+        with:
+          distribution: 'temurin'
+          java-version: '21'
+          cache: 'sbt'
+
+      - name: Build Scala.js
+        working-directory: browser-interpreter
+        run: sbt js/fastLinkJS
+
+      - name: Prepare deployment files
+        run: |
+          mkdir -p _site
+
+          # Find the Scala version from the build output
+          SCALA_VERSION=$(ls browser-interpreter/js/target/ | grep scala | head -1)
+          echo "Scala version: $SCALA_VERSION"
+
+          # Copy the demo HTML as index.html, updating the JS path if needed
+          sed "s|js/target/scala-[0-9.]*|js/target/$SCALA_VERSION|g" \
+            browser-interpreter/demo-compiler.html > _site/index.html
+
+          # Copy the generated JavaScript
+          mkdir -p "_site/js/target/$SCALA_VERSION"
+          cp -r "browser-interpreter/js/target/$SCALA_VERSION/browser-interpreter-js-fastopt" \
+            "_site/js/target/$SCALA_VERSION/"
+
+          # Add .nojekyll to prevent Jekyll processing
+          touch _site/.nojekyll
+
+          # Show what we're deploying
+          echo "Deployment contents:"
+          find _site -type f | head -20
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: '_site'
+
+  deploy:
+    # Only deploy on push to main/master or manual trigger with deploy=true
+    if: |
+      github.event_name == 'push' ||
+      (github.event_name == 'workflow_dispatch' && inputs.deploy)
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+

BROWSER_COMPILER_DESIGN_SIMPLE.md

@@ -0,0 +1,188 @@
+# Scala Browser Interpreter
+
+A proof-of-concept TASTy-based interpreter that runs Scala code in the browser.
+
+## Quick Start
+
+### Run the Demo
+
+Simply open `demo.html` in your web browser:
+
+```bash
+open demo.html
+```
+
+The demo includes several built-in examples:
+- Hello World - Basic println
+- Arithmetic - Math operations
+- Fibonacci - Recursive functions
+- Pattern Matching - Match expressions with guards
+- List Operations - map, filter, foldLeft
+- Option Handling - Some/None
+- Try/Catch - Exception handling
+- Higher-Order Functions - Functions as values
+- Factorial - Recursion
+- Closures - Captured variables
+
+### Convert Real Scala Code
+
+1. **Compile Scala to TASTy:**
+   ```bash
+   scalac -Yretain-trees examples/HelloWorld.scala -d out
+   ```
+
+2. **Convert TASTy to JSON:**
+   ```bash
+   sbt "browserInterpreterJvm/run out/HelloWorld.tasty"
+   ```
+
+3. **Paste the JSON output into the demo and run!**
+
+## Project Structure
+
+```
+browser-interpreter/
+├── demo.html              # Self-contained browser demo
+├── build.sbt              # SBT build configuration
+├── jvm/                   # JVM tools
+│   └── src/main/scala/browser/
+│       ├── TastyToJsonConverter.scala  # TASTy → JSON converter
+│       └── AstSerializer.scala         # Tree serializer
+├── js/                    # Scala.js browser module
+│   └── src/main/scala/browser/
+│       └── BrowserInterpreter.scala    # Scala.js interpreter
+└── examples/              # Example Scala programs
+    ├── HelloWorld.scala
+    ├── Fibonacci.scala
+    ├── PatternMatching.scala
+    └── ListOperations.scala
+```
+
+## JSON AST Format
+
+The interpreter uses a simple JSON AST format:
+
+```json
+// Literals
+{"tag": "Literal", "type": "Int", "value": 42}
+{"tag": "Literal", "type": "String", "value": "hello"}
+
+// Variables
+{"tag": "Ident", "name": "x"}
+
+// Binary operations
+{"tag": "BinaryOp", "op": "+", "lhs": {...}, "rhs": {...}}
+
+// Blocks
+{"tag": "Block", "stats": [...], "expr": {...}}
+
+// Conditionals
+{"tag": "If", "cond": {...}, "thenp": {...}, "elsep": {...}}
+
+// Loops
+{"tag": "While", "cond": {...}, "body": {...}}
+
+// Function definitions
+{"tag": "DefDef", "name": "add", "params": ["a", "b"], "body": {...}}
+
+// Function calls
+{"tag": "Apply", "fn": {...}, "args": [...]}
+
+// Lambdas
+{"tag": "Lambda", "params": ["x"], "body": {...}}
+
+// Pattern matching
+{"tag": "Match", "selector": {...}, "cases": [
+  {"pattern": {...}, "guard": {...}, "body": {...}}
+]}
+
+// Exceptions
+{"tag": "Try", "block": {...}, "catches": [...], "finalizer": {...}}
+{"tag": "Throw", "expr": {...}}
+```
+
+## Supported Features
+
+| Feature | Status |
+|---------|--------|
+| Literals (Int, String, Boolean, etc.) | ✅ |
+| Variables (val, var) | ✅ |
+| Arithmetic (+, -, *, /, %) | ✅ |
+| Comparisons (<, >, <=, >=, ==, !=) | ✅ |
+| Boolean operators (&&, \|\|, !) | ✅ |
+| Conditionals (if/else) | ✅ |
+| Loops (while) | ✅ |
+| Blocks with local definitions | ✅ |
+| Functions (def) | ✅ |
+| Recursion | ✅ |
+| Lambdas | ✅ |
+| Closures with captured variables | ✅ |
+| Pattern matching | ✅ |
+| Guards in pattern matching | ✅ |
+| Option (Some/None) | ✅ |
+| List operations (map, filter, fold, etc.) | ✅ |
+| String operations | ✅ |
+| Tuple operations | ✅ |
+| Try/Catch/Finally | ✅ |
+| Throw | ✅ |
+| For comprehensions | ⚠️ Partial |
+| Classes | ❌ |
+| Traits | ❌ |
+| Imports | N/A (compile-time) |
+
+## Building
+
+### Prerequisites
+- SBT 1.10+
+- Scala 3.7.0+
+- Node.js (for Scala.js testing)
+
+### Build Commands
+
+```bash
+# Compile everything
+sbt compile
+
+# Build JVM tools
+sbt browserInterpreterJvm/compile
+
+# Build Scala.js module
+sbt browserInterpreterJs/fastLinkJS
+
+# Run TASTy converter
+sbt "browserInterpreterJvm/run path/to/file.tasty"
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Compilation Pipeline                      │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│  Scala Source → scalac → TASTy → TastyToJson → JSON AST     │
+│                                                              │
+├─────────────────────────────────────────────────────────────┤
+│                    Browser Execution                         │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│  JSON AST → BrowserInterpreter.interpret() → Output          │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Roadmap
+
+- [x] Basic interpreter with control flow
+- [x] Pattern matching support
+- [x] Exception handling
+- [x] Collection operations
+- [x] TASTy-to-JSON converter
+- [ ] Cross-compile full interpreter to Scala.js
+- [ ] Bundle stdlib TASTy for type-checking
+- [ ] Full browser-based compilation
+
+## License
+
+Apache 2.0 (same as Scala 3)
+

CROSS_COMPILATION_FEASIBILITY.md

@@ -0,0 +1,58 @@
+import sbt.Keys._
+
+val scala3Version = "3.7.0"
+
+// Shared settings
+lazy val commonSettings = Seq(
+  version := "0.1.0-SNAPSHOT",
+  scalaVersion := scala3Version,
+  scalacOptions ++= Seq("-deprecation", "-feature")
+)
+
+// Shared code (cross-compiled to JVM and JS)
+lazy val shared = crossProject(JVMPlatform, JSPlatform)
+  .crossType(CrossType.Pure)
+  .in(file("shared"))
+  .settings(commonSettings)
+  .settings(
+    name := "browser-interpreter-shared"
+  )
+
+lazy val sharedJVM = shared.jvm
+lazy val sharedJS = shared.js
+
+// JVM project for TASTy-to-JSON conversion tools
+lazy val jvm = project
+  .in(file("jvm"))
+  .dependsOn(sharedJVM)
+  .settings(commonSettings)
+  .settings(
+    name := "browser-interpreter-jvm",
+    libraryDependencies ++= Seq(
+      "org.scala-lang" %% "scala3-tasty-inspector" % scala3Version
+    ),
+    Compile / mainClass := Some("browser.TastyToJsonConverter")
+  )
+
+// Scala.js project for browser execution
+lazy val js = project
+  .in(file("js"))
+  .enablePlugins(ScalaJSPlugin)
+  .dependsOn(sharedJS)
+  .settings(commonSettings)
+  .settings(
+    name := "browser-interpreter-js",
+    scalaJSUseMainModuleInitializer := false,
+    scalaJSLinkerConfig ~= { _.withModuleKind(ModuleKind.ESModule) },
+    libraryDependencies += "org.scala-js" %%% "scalajs-dom" % "2.8.0"
+  )
+
+// Root project
+lazy val root = project
+  .in(file("."))
+  .aggregate(sharedJVM, sharedJS, jvm, js)
+  .settings(commonSettings)
+  .settings(
+    name := "browser-interpreter",
+    publish / skip := true
+  )