redscript-mc 2.6.2 → 3.0.0

package/.github/workflows/ci.yml

@@ -10,6 +10,11 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+      - name: Checkout redscript-docs
+        uses: actions/checkout@v4
+        with:
+          repository: bkmashiro/redscript-docs
+          path: redscript-docs
       - uses: actions/setup-node@v4
         with:
           node-version: 20
@@ -17,6 +22,12 @@ jobs:
       - run: npm install
       - run: npm run build
       - run: npm test
+      - name: Run MC integration tests (offline - graceful skip)
+        run: npx jest --testPathPattern="mc-integration" --forceExit
+        env:
+          MC_OFFLINE: "true"
+      - name: Check stdlib docs are up to date
+        run: npx ts-node scripts/gen-docs.ts --check --docs-dir redscript-docs
 
   build:
     runs-on: ubuntu-latest

package/CHANGELOG.md

@@ -2,31 +2,40 @@
 
 All notable changes to RedScript will be documented in this file.
 
-## [Unreleased] — v3.0.0
+## [Unreleased]
 
-> **Status:** Active development. All stdlib modules below are merged to `main`; language features are stabilised pending final integration tests.
+## [3.0.0] - 2026-03-21
 
 ### Added
 
 #### Language / Compiler
 - **`match` expression** — pattern-match on int / enum values; compiles to `execute if score` chains with exhaustiveness checking
+- **`break` / `continue` statements** — structured loop control now lowers cleanly through HIR/MIR/LIR and is covered by unit, e2e, and MC integration tests
+- **`do { ... } while (...)` and `repeat N { ... }` loops** — post-test and fixed-count loop forms added to the parser, lowering pipeline, and compiler tests
+- **`const` declarations** — compile-time constants inline at use sites for simpler generated datapacks and cleaner constant propagation
+- **`@deprecated("message")` decorator** — compile-time warnings for deprecated APIs and migration guidance at call sites
 - **`for item in array` iteration** — `for x in arr { … }` syntax sugar; desugars to `while idx < arr.len() { let x = arr[idx]; idx++ }` in HIR; generates loop-header / loop-body / loop-exit mcfunction splits
 - **`arr.len()` — literal constant + dynamic runtime** — literal arrays (`[1,2,3].len()`) fold to a compile-time constant (`scoreboard players set`); function-parameter and heap arrays use the new `nbt_list_len` MIR instruction which lowers to `execute store result score … run data get storage`
+- **`@on(EventType)` full compiler implementation** — compiler generates Minecraft function-tag JSON and wires an `events.mcrs` dispatcher automatically; supported events: `PlayerJoin`, `PlayerDeath`, `EntityKill`, `ItemUse` (each with correctly typed parameters)
+
+#### Standard Library
+- **`Result<T>`** — new stdlib result type with `Ok` / `Err` variants and helper functions for explicit error handling
 - **`state.mcrs`** — persistent entity/global state management stdlib module
 - **`dialog.mcrs`** — NPC dialog trees with choice branching and callback support
 - **`scheduler.mcrs`** — tick-budget-aware task scheduler (coroutine-compatible)
-
-#### Tests
-- **Coverage: 80% → 85%** — new unit tests for builtins, runtime, emit pipeline, and stdlib modules; arr.len() compile-time and dynamic paths fully covered
-
-#### stdlib
 - **`linalg.mcrs`** — double-precision linear algebra: `vec2_add/sub/scale/dot/length/normalize`, `vec3_cross`, `mat2x2 / mat3x3 / mat4x4` multiply, Cramer's rule solver for 2×2 and 3×3 systems
 - **`fft.mcrs`** — Discrete Fourier Transform with a `@coroutine` variant for in-game use; supports transforms up to n=64; quarter-wave symmetry test now enabled after related compiler fix
 - **`ecs.mcrs`** — Entity Component System: `register_component`, `get_component`, `has_component`; built-in Health and Velocity components; `@tick` system iteration via `foreach(entity[tag=has_<component>])`; fills the gap that Java datapacks have vs Bedrock's native component model
 - **`sort.mcrs` v2** — coroutine-based bottom-up merge sort for large arrays (n > 64); yields every 20 comparisons to stay within the 20 ms tick budget
 
-#### Language / Events
-- **`@on(EventType)` full compiler implementation** — compiler generates Minecraft function-tag JSON and wires an `events.mcrs` dispatcher automatically; supported events: `PlayerJoin`, `PlayerDeath`, `EntityKill`, `ItemUse` (each with correctly typed parameters)
+#### Examples
+- **7 new example programs** — `rpg/health_system`, `rpg/boss_fight`, `rpg/inventory`, `game/tower_defense`, `game/racing`, `math/physics_sim`, and `util/debug_hud`
+
+#### Documentation
+- **Language reference expansion** — `docs/LANGUAGE_REFERENCE.md` now documents the current type system plus expression, statement, decorator, execute-context, selector, coordinate, and builtin semantics in one place
+
+#### Tests
+- **Coverage increased further across compiler subsystems** — `src/typechecker/index.ts` branch coverage reached **88.33%**, `src/optimizer/**` line coverage reached **96.21%** (~97%), and `src/optimizer/coroutine.ts` function coverage reached **94.23%**
 - **MC integration tests** for `@on(PlayerJoin)` and `@on(PlayerDeath)` added to the test suite
 
 #### Runtime

package/README-benchmarks.md

@@ -0,0 +1,48 @@
+# Benchmark Suite
+
+RedScript now ships two benchmark entrypoints under `benchmarks/`.
+
+## What They Measure
+
+`benchmarks/compiler-perf.ts`
+
+- Generates synthetic RedScript programs at roughly 10, 100, and 1000 lines.
+- Measures end-to-end compiler stage time for:
+  - `parse`: preprocess, lex, parse, import merge, typecheck
+  - `HIR`: AST to HIR lowering and monomorphization
+  - `MIR`: MIR lowering, optimization, coroutine transform, and LIR lowering/optimization
+  - `emit`: datapack file emission
+- Emits a JSON report to stdout.
+
+`benchmarks/stdlib-complexity.ts`
+
+- Compiles every file in `src/stdlib/`.
+- Reports emitted instruction count, file count, and artifact size.
+- Compares three optimization presets:
+  - `O0`: no MIR/LIR optimization passes
+  - `O1`: current default optimization pipeline
+  - `O2`: `O1` plus a second MIR/LIR optimization round after coroutine lowering
+
+## How To Run
+
+Run the default compiler benchmark:
+
+```bash
+npm run bench
+```
+
+Write the compiler benchmark report to a file:
+
+```bash
+npx ts-node benchmarks/compiler-perf.ts --iterations 5 --output benchmarks/compiler-perf.report.json
+```
+
+Run the stdlib complexity benchmark:
+
+```bash
+npx ts-node benchmarks/stdlib-complexity.ts --output benchmarks/stdlib-complexity.report.json
+```
+
+## Baseline
+
+`benchmarks/baseline.json` stores one recorded run of both benchmarks on the local machine. Treat it as a local baseline, not a cross-machine performance target.

package/README-vscode-test.md

@@ -0,0 +1,251 @@
+# VSCode Extension Manual Test Guide
+
+The RedScript VSCode extension (`editors/vscode/`) provides syntax highlighting,
+code completion, hover documentation, and error diagnostics for `.mcrs` files.
+Because the extension runs inside a VS Code host process, automated integration
+tests require the `@vscode/test-electron` or `@vscode/test-cli` harness and an
+Xvfb display server (or Electron headless mode).  The steps below describe how
+to run the manual test cases by hand, plus a scaffold for future automation.
+
+---
+
+## 1. Prerequisites
+
+```bash
+cd editors/vscode
+npm install
+npm run build   # produces out/ from src/
+```
+
+Install the extension from VSIX into VS Code:
+
+```bash
+code --install-extension redscript-vscode-*.vsix
+```
+
+Or open `editors/vscode/` in VS Code and press **F5** to launch an Extension
+Development Host.
+
+---
+
+## 2. Test Cases
+
+### 2.1 Syntax Highlighting – `.mcrs` file loaded
+
+**File to open:** any `.mcrs` file, e.g. `examples/hello.mcrs`.
+
+Expected token colourisation (use **Developer: Inspect Editor Tokens and Scopes**):
+
+| Token                  | Expected scope                              |
+|------------------------|---------------------------------------------|
+| `fn`                   | `keyword.declaration.redscript`             |
+| `let`                  | `keyword.declaration.redscript`             |
+| `if`, `while`, `return`| `keyword.control.redscript`                 |
+| `true`, `false`        | `constant.language.boolean.redscript`       |
+| `self`                 | `variable.language.self.redscript`          |
+| `int`, `bool`, `string`| `support.type.primitive.redscript`          |
+| `@keep`, `@load`       | `meta.decorator.redscript`                  |
+| `// comment`           | `comment.line.double-slash.redscript`       |
+| `"hello"`              | `string.quoted.double.redscript`            |
+| `42`, `3.14`           | `constant.numeric.redscript`                |
+| `@p`, `@a`, `@e`       | `entity.name.selector.redscript`            |
+
+**Pass criteria:** every token above shows the expected scope in the inspector.
+
+---
+
+### 2.2 Code Completion – keywords and builtins
+
+1. Create a new file `test.mcrs` with:
+   ```redscript
+   fn example() {
+       sc
+   ```
+2. Place the cursor after `sc` and press **Ctrl+Space**.
+
+**Expected:** `scoreboard_get`, `scoreboard_set`, `scoreboard_add` appear in the
+completion list with their signatures.
+
+3. Type `say(` and hover over it.
+
+**Expected:** completion or IntelliSense shows `say(msg: string)` signature.
+
+4. Type `fn ` at the top level.
+
+**Expected:** snippet for a function declaration is offered.
+
+---
+
+### 2.3 Error Diagnostics – red underline on syntax errors
+
+1. Open or create `test.mcrs` with an intentional error:
+   ```redscript
+   fn broken() {
+       let x: int = ;   // missing right-hand side
+   }
+   ```
+2. Wait ≤ 600 ms (the debounce interval).
+
+**Expected:** the `;` (or the assignment) is underlined in red; the Problems
+panel shows an error from the RedScript compiler.
+
+3. Fix the error (`let x: int = 42;`) and save.
+
+**Expected:** the red underline disappears within ~600 ms.
+
+---
+
+### 2.4 Hover Documentation
+
+1. Open any `.mcrs` file that uses a builtin, e.g.:
+   ```redscript
+   fn t() { scoreboard_set("@s", "score", 10); }
+   ```
+2. Hover over `scoreboard_set`.
+
+**Expected:** a Markdown hover card appears showing:
+- Signature: `scoreboard_set(target, objective, value)`
+- Description from the builtin docs table in `src/hover.ts`
+- Example usage (if present)
+
+3. Hover over a user-defined function in the same file.
+
+**Expected:** if the function has a `///` doc comment immediately above it,
+that comment text appears in the hover.
+
+---
+
+## 3. Automated Test Scaffold (future)
+
+The following test file can be placed at
+`editors/vscode/src/test/extension.test.ts` once `@vscode/test-electron` is
+added as a dev dependency and a Mocha runner is configured in `package.json`.
+
+```typescript
+// editors/vscode/src/test/extension.test.ts
+// Automated integration tests for the RedScript VSCode extension.
+// Run via: npx @vscode/test-electron --extensionDevelopmentPath=. --extensionTestsPath=./out/test
+//
+// Requires: @vscode/test-electron, mocha, @types/mocha
+
+import * as assert from 'assert'
+import * as path from 'path'
+import * as vscode from 'vscode'
+
+const FIXTURE = path.join(__dirname, '..', '..', 'fixtures', 'test.mcrs')
+
+suite('RedScript VSCode Extension', function () {
+  this.timeout(10_000)
+
+  let document: vscode.TextDocument
+
+  suiteSetup(async () => {
+    // Ensure the extension is activated before tests run.
+    await vscode.extensions.getExtension('redscript.redscript-vscode')?.activate()
+    document = await vscode.workspace.openTextDocument(FIXTURE)
+    await vscode.window.showTextDocument(document)
+    // Allow diagnostics to settle (debounce is 600 ms).
+    await new Promise(r => setTimeout(r, 800))
+  })
+
+  // ── 2.1 Syntax Highlighting ─────────────────────────────────────────────────
+  test('grammar is registered for .mcrs files', () => {
+    assert.strictEqual(document.languageId, 'redscript')
+  })
+
+  // ── 2.2 Completions ─────────────────────────────────────────────────────────
+  test('completion list includes scoreboard_set', async () => {
+    const pos = new vscode.Position(5, 10)  // after "sc" on line 5
+    const list = await vscode.commands.executeCommand<vscode.CompletionList>(
+      'vscode.executeCompletionItemProvider',
+      document.uri,
+      pos
+    )
+    const labels = (list?.items ?? []).map(i =>
+      typeof i.label === 'string' ? i.label : i.label.label
+    )
+    assert.ok(labels.some(l => l.includes('scoreboard_set')), `Expected scoreboard_set in: ${labels.join(', ')}`)
+  })
+
+  test('completion list includes keyword "fn"', async () => {
+    const pos = new vscode.Position(0, 0)
+    const list = await vscode.commands.executeCommand<vscode.CompletionList>(
+      'vscode.executeCompletionItemProvider',
+      document.uri,
+      pos
+    )
+    const labels = (list?.items ?? []).map(i =>
+      typeof i.label === 'string' ? i.label : i.label.label
+    )
+    assert.ok(labels.some(l => l === 'fn'), `Expected "fn" keyword in completions`)
+  })
+
+  // ── 2.3 Diagnostics ─────────────────────────────────────────────────────────
+  test('no diagnostics on valid file', async () => {
+    const diags = vscode.languages.getDiagnostics(document.uri)
+    assert.strictEqual(diags.length, 0, `Unexpected diagnostics: ${diags.map(d => d.message).join('; ')}`)
+  })
+
+  test('syntax error produces a diagnostic', async () => {
+    const edit = new vscode.WorkspaceEdit()
+    const errorLine = 'fn broken() { let x: int = ; }\n'
+    edit.insert(document.uri, new vscode.Position(document.lineCount, 0), errorLine)
+    await vscode.workspace.applyEdit(edit)
+    await new Promise(r => setTimeout(r, 800))
+
+    const diags = vscode.languages.getDiagnostics(document.uri)
+    assert.ok(diags.length > 0, 'Expected at least one error diagnostic for broken syntax')
+  })
+
+  // ── 2.4 Hover ───────────────────────────────────────────────────────────────
+  test('hover on scoreboard_set returns documentation', async () => {
+    // Position on "scoreboard_set" in the fixture file (line 2, col 4)
+    const pos = new vscode.Position(2, 6)
+    const hovers = await vscode.commands.executeCommand<vscode.Hover[]>(
+      'vscode.executeHoverProvider',
+      document.uri,
+      pos
+    )
+    const text = (hovers ?? [])
+      .flatMap(h => h.contents)
+      .map(c => (typeof c === 'string' ? c : c.value))
+      .join('\n')
+    assert.ok(text.includes('scoreboard'), `Expected hover docs to mention 'scoreboard', got: ${text}`)
+  })
+})
+```
+
+A matching fixture file (`editors/vscode/fixtures/test.mcrs`):
+
+```redscript
+// Fixture for VSCode extension integration tests
+fn example() {
+    scoreboard_set("@s", "score", 10);
+    say("hello");
+}
+
+// sc   ← cursor here for completion test (line 5, col 10)
+```
+
+---
+
+## 4. Build & Run (CI)
+
+Add to `editors/vscode/package.json` scripts when the automated scaffold is ready:
+
+```json
+"test": "node ./out/test/runTests.js"
+```
+
+And install:
+
+```bash
+npm install --save-dev @vscode/test-electron mocha @types/mocha
+```
+
+For headless CI:
+
+```bash
+Xvfb :99 -screen 0 1024x768x24 &
+DISPLAY=:99 npm test
+```

package/RELEASE_NOTES.md

@@ -0,0 +1,74 @@
+# RedScript v3.0.0 — Release Notes
+
+## Highlights
+
+RedScript v3.0.0 is a major release that brings a comprehensive optimization pipeline, new language features, improved tooling, and complete stdlib documentation.
+
+## What's New
+
+### 🚀 Optimizer Pipeline (7 new passes)
+
+| Pass | Description |
+|------|-------------|
+| Tail Call Optimization (TCO) | Converts tail-recursive functions to loops, avoiding MC's ~512-depth call limit |
+| Common Subexpression Elimination (CSE) | Caches repeated expressions, eliminating redundant computation |
+| Auto-Inline | Automatically inlines functions ≤5 MIR instructions |
+| Execute Chain Optimization | Merges `execute if A run execute if B` → `execute if A if B` |
+| Strength Reduction | `x * 2` → `x + x`, algebraic simplifications |
+| Scoreboard Read Batching | Deduplicates redundant scoreboard reads within a block |
+| NBT Write Coalescing | Removes overwritten NBT writes (backward analysis) |
+
+### 🆕 Language Features
+
+- **`struct extends`** — compile-time field inheritance, zero runtime overhead
+- **`break <label>` / `continue <label>`** — jump out of nested loops
+- **`@memoize`** — LRU-1 function result caching for single-arg int functions
+- **`@throttle(ticks)`** — rate-limit function execution to once per N ticks
+- **`@retry(max)`** — auto-retry on failure, up to N times
+
+### 🛠️ CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `redscript test` | Run `@test`-annotated functions with built-in `assert` |
+| `redscript publish` | Package compiled output as standard Minecraft datapack `.zip` |
+| `redscript docs [module]` | Open stdlib documentation in browser |
+| `redscript lint` | 5 static analysis rules (unused-var, magic-number, dead-branch, ...) |
+| `redscript.toml` | Project configuration file — replaces CLI flags |
+
+### 🔧 Tooling & LSP
+
+- **LSP hover**: Shows `///` doc comments on hover (description, @param, @returns)
+- **LSP diagnostics**: Lint warnings pushed to editor Problems panel in real-time
+- **Source map**: Generated `.sourcemap.json` traces `.mcfunction` back to `.mcrs` lines
+- **Playground share**: URL-encoded shareable links via lz-string compression
+
+### 📚 Stdlib (50 modules, complete documentation)
+
+All 50 stdlib modules now have:
+- `///` doc comment annotations with `@since`, `@param`, `@returns`, `@example`
+- Auto-generated English + Chinese documentation
+- VitePress `<Badge>` version tags
+
+New modules added: `queue`, `map`, `set_int`, `sets`
+
+### 🧪 Testing
+
+- **3,886 unit tests passing**, 0 failing
+- **430 MC integration tests** (with live Minecraft server)
+- Overall branch coverage: **81.5%**
+
+## Breaking Changes
+
+- `format_string` type is now unified as `string` — remove any `as string` workarounds
+- `arr.len()` for literal arrays returns compile-time constants — some dynamic expectations changed
+
+## Migration from v2.x
+
+1. Update package: `npm install redscript-mc@3.0.0`
+2. Replace `as string` on format strings (no longer needed)
+3. Add `redscript.toml` to your project (optional, run `redscript init` to generate)
+
+## Full Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md) for detailed commit history.