Merge branch 'master' into docstrings-before-type-expansions

Author: mediremi

.devcontainer/.dockerignore

@@ -0,0 +1,99 @@
+*~
+_build
+*.obj
+*.out
+*.compile
+*.native
+*.byte
+*.cmo
+*.annot
+*.cmi
+*.cmx
+*.cmt
+*.cmti
+*.cma
+*.a
+*.cmxa
+*.obj
+ *~
+*.annot
+*.mj
+*.bak
+*.swp
+*.swo
+*.flambda
+*.jsx
+*.lambda
+*.rawlambda
+*.s
+*.o
+*.lam
+*.0.js
+*#
+*.log
+.#*
+*.cmj
+*.rawlambda
+*.lambda
+*.zip
+*.mlast
+*.mliast
+
+.idea
+.DS_Store
+
+node_modules
+*.dump
+coverage
+
+.ninja_log
+.bsdeps
+.bsbuild
+lib/ocaml
+tests/build_tests/*/lib/
+#ignore temporary directory
+*.goog.js
+*.jsoo.js
+*.so
+tmp/
+tracing*.json
+
+_opam
+
+.env
+playground/packages/
+playground/stdlib/
+playground/*.cmj
+playground/*.cmi
+playground/.netrc
+playground/compiler.*js
+
+rewatch/target/
+rewatch/rewatch
+
+tests/tools_tests/**/*.res.js
+tests/tools_tests/lib
+tests/analysis_tests*/lib
+tests/analysis_tests/**/*.bs.js
+
+/linux/*.exe
+/linuxarm64/*.exe
+/darwin/*.exe
+/darwinarm64/*.exe
+/win32/*.exe
+
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/sdks
+!.yarn/versions
+
+*.tsbuildinfo
+
+# package tarballs
+package.tgz
+*.exe
+
+/ninja/ninja
+/ninja/build.ninja

.devcontainer/Dockerfile

@@ -2,10 +2,14 @@ FROM mcr.microsoft.com/devcontainers/rust:1-1-bookworm
 LABEL org.opencontainers.image.authors="Christoph Knittel <[email protected]>"
 LABEL org.opencontainers.image.description="Docker image for ReScript development."
 
-RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
+RUN sudo apt-get update && export DEBIAN_FRONTEND=noninteractive \
     && apt-get -y install --no-install-recommends \
-    yarn \
-    opam \
+    cmake \
+    ninja-build \
     musl-tools \
     python-is-python3 \
     && rm -rf /var/lib/apt/lists/*
+
+# Install OPAM
+ARG OPAM_VERSION=2.4.1
+RUN printf '\n\n' | bash -c "sh <(curl -fsSL https://raw.githubusercontent.com/ocaml/opam/master/shell/install.sh) --version $OPAM_VERSION"

.devcontainer/devcontainer.json

@@ -2,7 +2,11 @@
   "name": "ReScript Compiler",
   "build": {
     "context": ".",
-    "dockerfile": "Dockerfile"
+    "dockerfile": "Dockerfile",
+    "args": {
+      "USER_UID": "${localEnv:UID}",
+      "USER_GID": "${localEnv:GID}"
+    }
   },
   "features": {
     "ghcr.io/devcontainers/features/github-cli:1": {
@@ -23,5 +27,7 @@
       ]
     }
   },
-  "postCreateCommand": ".devcontainer/postCreate.sh"
+  "postCreateCommand": ".devcontainer/postCreate.sh",
+  "remoteUser": "vscode",
+  "containerUser": "vscode"
 }

.devcontainer/postCreate.sh

@@ -2,14 +2,14 @@
 
 # Install dev dependencies from OPAM
 opam init -y --bare --disable-sandboxing
-opam switch create 5.3.0 --packages ocaml-option-static
-opam install . --deps-only -y
-
-# For IDE support, install the OCaml language server
-opam install ocaml-lsp-server -y
+opam switch create 5.3.0
+opam install . --deps-only --with-test --with-dev-setup -y
 
 # Add OPAM environment setup to shell startup script
 echo 'eval $(opam env)' >> ~/.zshrc
 echo 'eval $(opam env)' >> ~/.bashrc
 
-npm install --ignore-scripts
+nvm install
+
+corepack enable
+printf "\n" | yarn 

.github/workflows/ci.yml

@@ -80,6 +80,7 @@ jobs:
       OPAM_VERSION: 2.3.0
       DUNE_PROFILE: release
       RUST_BACKTRACE: "1"
+      RUSTFLAGS: "-Dwarnings"
 
     steps:
       - name: "Windows: Set git config"
@@ -131,16 +132,21 @@ jobs:
         run: |
           cargo build --manifest-path rewatch/Cargo.toml --target ${{ matrix.rust-target }} --release
 
+      - name: Lint rewatch
+        if: steps.rewatch-build-cache.outputs.cache-hit != 'true'
+        run: |
+          cargo clippy --manifest-path rewatch/Cargo.toml --all-targets --all-features
+
       - name: Run rewatch unit tests
         if: steps.rewatch-build-cache.outputs.cache-hit != 'true'
         run: |
-          cargo test --manifest-path rewatch/Cargo.toml
+          cargo test --manifest-path rewatch/Cargo.toml --release
 
       - name: Copy rewatch binary
         run: |
-          cp rewatch/target/${{ matrix.rust-target }}/release/rewatch${{ runner.os == 'Windows' && '.exe' || '' }} rewatch
+          cp rewatch/target/${{ matrix.rust-target }}/release/rescript${{ runner.os == 'Windows' && '.exe' || '' }} rescript
           mkdir -p rewatch/target/release
-          cp rewatch/target/${{ matrix.rust-target }}/release/rewatch${{ runner.os == 'Windows' && '.exe' || '' }} rewatch/target/release
+          cp rewatch/target/${{ matrix.rust-target }}/release/rescript${{ runner.os == 'Windows' && '.exe' || '' }} rewatch/target/release
           ./scripts/copyExes.js --rewatch
         shell: bash
 
@@ -360,6 +366,14 @@ jobs:
         if: runner.os != 'Windows'
         run: make -C tests/gentype_tests/typescript-react-example clean test
 
+      # On Windows, after running setup-ocaml (if it wasn't cached yet or the cache couldn't be restored),
+      # Cygwin bash is used instead of Git Bash for Windows, breaking the rewatch tests.
+      # So we need to adjust the path to bring back Git Bash for Windows.
+      - name: Rewatch tests need Git Bash for Windows
+        if: ${{ runner.os == 'Windows' }}
+        run: echo "C:\Program Files\Git\bin" >> $GITHUB_PATH
+        shell: bash
+
       - name: Run rewatch tests
         run: ./rewatch/tests/suite-ci.sh
         shell: bash

.gitignore

@@ -99,3 +99,6 @@ tests/analysis_tests/**/*.bs.js
 # package tarballs
 package.tgz
 *.exe
+
+# AI Agents
+.claude/settings.local.json

.mcp.json

@@ -0,0 +1,139 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is the ReScript compiler repository - a robustly typed language that compiles to efficient and human-readable JavaScript. ReScript is built using OCaml and includes a complete toolchain with compiler, build system, syntax parser, and standard library.
+
+## Build Commands
+
+### Basic Development
+```bash
+# Build compiler and copy executables
+make
+
+# Build in watch mode 
+make watch
+
+# Build everything including standard library
+make lib
+
+# Build artifacts and update artifact list
+make artifacts
+```
+
+### Testing
+```bash
+# Run all tests
+make test
+
+# Run specific test types
+make test-syntax           # Syntax parser tests
+make test-syntax-roundtrip # Roundtrip syntax tests  
+make test-gentype         # GenType tests
+make test-analysis        # Analysis tests
+make test-tools           # Tools tests
+make test-rewatch         # Rewatch tests
+
+# Run single file test
+./cli/bsc.js myTestFile.res
+
+# View parse/typed trees for debugging
+./cli/bsc.js -dparsetree myTestFile.res
+./cli/bsc.js -dtypedtree myTestFile.res
+```
+
+### Code Quality
+```bash
+# Format code
+make format
+
+# Check formatting
+make checkformat
+
+# Lint with Biome
+npm run check
+npm run check:all
+
+# TypeScript type checking  
+npm run typecheck
+```
+
+### Clean Operations
+```bash
+make clean      # Clean OCaml build artifacts
+make clean-all  # Clean everything including Rust/gentype
+```
+
+## Compiler Architecture
+
+The ReScript compiler follows this high-level pipeline:
+
+```
+ReScript Source (.res)
+  ↓ (ReScript Parser - compiler/syntax/)
+Surface Syntax Tree  
+  ↓ (Frontend transformations - compiler/frontend/)
+Surface Syntax Tree
+  ↓ (OCaml Type Checker - compiler/ml/)
+Typedtree
+  ↓ (Lambda compilation - compiler/core/lam_*)
+Lambda IR
+  ↓ (JS compilation - compiler/core/js_*)  
+JS IR
+  ↓ (JS output - compiler/core/js_dump*)
+JavaScript Code
+```
+
+### Key Directories
+
+- **`compiler/syntax/`** - ReScript syntax parser (MIT licensed, separate from main LGPL)
+- **`compiler/frontend/`** - AST transformations, external FFI processing, built-in attributes
+- **`compiler/ml/`** - OCaml compiler infrastructure (type checker, typedtree, etc.)
+- **`compiler/core/`** - Core compilation:
+  - `lam_*` files: Lambda IR compilation and optimization passes
+  - `js_*` files: JavaScript IR and code generation
+- **`compiler/ext/`** - Extended utilities and data structures
+- **`compiler/bsb/`** - Build system implementation
+- **`compiler/gentype/`** - TypeScript generation
+- **`runtime/`** - ReScript standard library (written in ReScript)
+- **`lib/`** - Compiled JavaScript output of standard library
+- **`analysis/`** - Language server and tooling support
+
+### Build System Components
+
+- **`compiler/bsb_exe/`** - Main ReScript build tool entry point
+- **`compiler/bsc/`** - Compiler binary entry point  
+- **`rewatch/`** - File watcher (written in Rust)
+- **`ninja/`** - Vendored Ninja build system
+
+## Development Setup Notes
+
+- Uses OCaml 5.3.0+ with opam for compiler development
+- Uses dune as build system with specific profiles (dev, release, browser)
+- Node.js 20+ required for JavaScript tooling
+- Rust toolchain needed for rewatch file watcher
+- Python ≤3.11 required for building ninja
+
+## Coding Conventions
+
+- **OCaml code**: snake_case (e.g., `to_string`)
+- **ReScript code**: camelCase (e.g., `toString`)
+- Use DCO sign-off for all commits: `Signed-Off-By: Your Name <email>`
+
+## Testing Strategy
+
+- **Mocha tests** (`tests/tests/`) - Runtime library unit tests
+- **Build system tests** (`tests/build_tests/`) - Integration tests  
+- **OUnit tests** (`tests/ounit_tests/`) - Compiler unit tests
+- **Expectation tests** - Plain `.res` files that check compilation output
+- Always include appropriate tests with new features/changes
+
+## Performance Notes
+
+The compiler is designed for fast feedback loops and scales to large codebases. When making changes:
+- Avoid introducing meaningless symbols
+- Maintain readable JavaScript output
+- Consider compilation speed impact
+- Use appropriate optimization passes in the Lambda and JS IRs