Merge branch 'master' into better-caching

Author: Frotty

.circleci/config.yml

@@ -17,8 +17,7 @@ jobs:
     working_directory: ~/repo/de.peeeq.wurstscript
 
     environment:
-      # Customize the JVM maximum heap limit
-      JVM_OPTS: -Xmx3200m
+      GRADLE_OPTS: -Dorg.gradle.parallel=false -Dorg.gradle.workers.max=2
       TERM: dumb
 
     steps:
@@ -28,20 +27,18 @@ jobs:
       # Download and cache dependencies
       - restore_cache:
           keys:
-            - v1-dependencies-{{ checksum "build.gradle" }}
+            - v2-gradle-{{ checksum "build.gradle" }}-{{ checksum "gradle.properties" }}-{{ checksum "gradle/wrapper/gradle-wrapper.properties" }}
             # fallback to using the latest cache if no exact match is found
-            - v1-dependencies-
-
-      - run: ./gradlew dependencies
+            - v2-gradle-
 
       - save_cache:
           paths:
             - ~/.gradle
-          key: v1-dependencies-{{ checksum "build.gradle" }}
-
-      # run tests
-      - run: ./gradlew test --info
+          key: v2-gradle-{{ checksum "build.gradle" }}-{{ checksum "gradle.properties" }}-{{ checksum "gradle/wrapper/gradle-wrapper.properties" }}
 
-      # report tests results
-      - run: ./gradlew jacocoTestReport coveralls
+      # run tests and coverage in one invocation to avoid duplicate config/startup cost
+      - run:
+          name: Run tests and coverage
+          command: ./gradlew --no-daemon --stacktrace test jacocoTestReport coveralls
+          no_output_timeout: 30m
 

.github/workflows/build.yml

@@ -21,6 +21,9 @@ jobs:
     permissions:
       contents: read
     env:
+      JAVA_TOOL_OPTIONS: >-
+        -XX:+UseCompactObjectHeaders
+        -XX:+UseStringDeduplication
       GRADLE_OPTS: -Dorg.gradle.daemon=false
     defaults:
       run:
@@ -81,6 +84,14 @@ jobs:
         shell: bash
         run: ./gradlew packageSlimCompilerDist --no-daemon --stacktrace
 
+      - name: Prepare bundled Lua runtime (Linux)
+        if: runner.os == 'Linux'
+        shell: bash
+        run: |
+          if [[ -f src/test/resources/lua53 ]]; then
+            chmod +x src/test/resources/lua53
+          fi
+
       - name: Run tests
         shell: bash
         run: ./gradlew test --no-daemon --stacktrace
@@ -104,6 +115,18 @@ jobs:
     permissions:
       contents: write
     steps:
+      - name: Checkout (to update nightly tag)
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Move 'nightly' tag to this commit
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git tag -f nightly "$GITHUB_SHA"
+          git push origin nightly --force
+
       - name: Download all packaged artifacts
         uses: actions/download-artifact@v4
         with:
@@ -126,6 +149,7 @@ jobs:
             echo "ERROR: expected at least Win + Linux zips."
             exit 1
           fi
+
       - name: Normalize nightly filenames
         shell: bash
         run: |
@@ -139,52 +163,13 @@ jobs:
           done
           echo "Renamed to:"; ls -alh upload
 
-      # Delete old release + tag, then create a fresh one at HEAD
-      - name: Recreate nightly release and tag at HEAD
-        uses: actions/github-script@v7
-        with:
-          script: |
-            const { owner, repo } = context.repo;
-            const tag = 'nightly';
-
-            // Delete existing release (if any)
-            try {
-              const rel = await github.rest.repos.getReleaseByTag({ owner, repo, tag });
-              await github.rest.repos.deleteRelease({ owner, repo, release_id: rel.data.id });
-              core.info(`Deleted release id=${rel.data.id}`);
-            } catch (e) {
-              core.info(`No previous release to delete: ${e.message}`);
-            }
-
-            // Delete tag (if any)
-            try {
-              await github.rest.git.deleteRef({ owner, repo, ref: `tags/${tag}` });
-              core.info('Deleted ref tags/nightly');
-            } catch (e) {
-              core.info(`No existing tag to delete: ${e.message}`);
-            }
-
-            // Create fresh prerelease at the current commit
-            const { data: rel2 } = await github.rest.repos.createRelease({
-              owner, repo,
-              tag_name: tag,
-              target_commitish: context.sha,
-              name: 'Nightly Build (master)',
-              body: 'Nightly build for the latest commit on `master`.\nThis release is automatically updated on each push.',
-              draft: false,
-              prerelease: true,
-              make_latest: 'false'  // MUST be a string
-            });
-            core.setOutput('upload_url', rel2.upload_url);
-
       - name: Publish Nightly Release (upload assets)
         uses: softprops/action-gh-release@v2
         with:
           tag_name: nightly
-          target_commitish: ${{ github.sha }}
           prerelease: true
           draft: false
-          make_latest: "false"  # keep as string here too
+          make_latest: "false"
           name: Nightly Build (master)
           body: |
             Nightly build for the latest commit on `master`.
@@ -193,5 +178,3 @@ jobs:
           fail_on_unmatched_files: false
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-

AGENTS.md

@@ -0,0 +1,189 @@
+# AGENTS.md
+
+This document defines how automated coding assistants (“agents”) should interact with this repository.
+
+## 1. Repository Overview
+
+This repository contains the **WurstScript compiler**. Its main code lives in:
+
+```
+de.peeeq.wurstscript/
+```
+
+Other directories like `WurstPack` and `HelperScripts` exist but are largely **deprecated** and should not be modified unless explicitly requested.
+
+### Compiler layout
+
+Inside `de.peeeq.wurstscript`:
+
+* **`src/main/antlr/de/peeeq/wurstscript/antlr/`**
+  Contains the **ANTLR grammars** (`.g4`) for Wurst and Jass.
+  These produce concrete syntax trees (CSTs).
+
+* **`parserspec/`**
+  Contains **.parseq grammars** for `abstractsyntaxgen`
+  ([https://github.com/peterzeller/abstractsyntaxgen](https://github.com/peterzeller/abstractsyntaxgen)).
+  These define the AST structure used by the compiler.
+  Code is generated via the Gradle task:
+
+  ```
+  ./gradlew :gen
+  ```
+
+* **`src/main/java/de/peeeq/`**
+  Main compiler sources:
+
+  * Parsing and AST infrastructure
+  * Type checking
+  * Intermediate language (**IM**)
+  * Jass and Lua backends
+  * Interpreter for executing IM at compile time
+    (used for specific compile-time evaluations)
+
+### Compilation pipeline (simplified)
+
+1. Parse Wurst/Jass with ANTLR → CST
+2. Abstractsyntaxgen → AST
+3. Transform AST → IM
+4. Optionally: Run IM in the interpreter, Optimize
+5. Transform IM → Backend (Jass or Lua)
+
+
+### Language and tooling
+
+* **Java 25**
+* **Gradle (9.2.1)**
+* Unit tests define many entry points and expected behaviors.
+
+---
+
+## 2. Agent Expectations
+
+Changes made by agents must follow these principles:
+
+### Compatibility first
+
+* **All existing tests must continue to pass.**
+* If behavior changes intentionally, provide **new tests** that define the updated semantics.
+
+### Minimal, well-scoped edits
+
+Agents should:
+
+* Fix concrete bugs with **small, local patches**.
+* Add missing null-checks, defensive checks, or diagnostics where appropriate.
+* Add tests when resolving issues or implementing requested features.
+
+Agents should avoid:
+
+* Large refactors (renaming packages, structural moves, mass rewrites).
+* Modifying deprecated folders unless explicitly instructed.
+* Altering public semantics or language rules without tests demonstrating the intended outcome.
+
+### Test-driven
+
+* Any new behavior requires tests showing failure before the change and success after.
+* Use existing test style and harnesses.
+
+### Generated code
+
+* Do **not** modify files generated by `:gen`.
+* If modifying `.parseq` files or grammars, regenerate via:
+
+  ```
+  ./gradlew :gen
+  ```
+
+---
+
+## 3. Coding Guidelines
+
+### Follow existing style
+
+Use the conventions already present in the file you edit. Avoid introducing new patterns without reason.
+
+### Compiler structure expectations
+
+* The IM is the central intermediate representation.
+* Transformations should keep IM consistent and valid.
+* Backends (Jass/Lua) expect well-formed IM; avoid breaking invariants.
+* Interpreter should remain deterministic and side-effect free.
+
+### Error handling
+
+* Prefer explicit, descriptive diagnostic messages.
+* Avoid silent fallbacks or suppressed exceptions.
+* Don’t change the meaning of existing error messages unless required.
+
+### Performance
+
+* Avoid algorithmic regressions in parsing, type checking, or transforms.
+* Consider memory impact when manipulating large ASTs or IM graphs.
+
+---
+
+## 4. Allowed vs. Disallowed Changes
+
+### Allowed
+
+* Fix a crash or incorrect behavior in a specific compiler pass.
+* Add a regression test that demonstrates a known issue.
+* Improve clarity of error messages.
+* Add a small new feature when fully specified by the user and backed by tests.
+* Update Gradle/JDK usage only if part of a requested task.
+
+### Disallowed
+
+* Unsolicited rewrites of ANTLR grammars.
+* Modifying deprecated folders.
+* Changing code generation semantics without explicit tests.
+* Changing IM behavior without test coverage.
+* Introducing new external dependencies unless requested.
+
+---
+
+## 5. How to Run Tests and Code Generation
+
+Inside
+
+```
+de.peeeq.wurstscript/
+```
+
+run:
+
+### Run all tests
+
+```
+./gradlew test
+```
+
+### Run a specific test
+
+```
+./gradlew test --tests "tests.wurstscript.tests.GenericsWithTypeclassesTests.identity"
+```
+
+### Generate AST code via ANTLR & abstractsyntaxgen
+
+```
+./gradlew :gen
+```
+
+### Build the compiler
+
+```
+./gradlew build
+```
+
+---
+
+## 6. Summary for Agents
+
+* Keep changes **minimal**, **compatible**, and **tested**.
+* The authoritative behavior is defined by the **existing test suite**.
+* The compiler architecture relies on CST → AST → IM → Backend; treat each stage carefully.
+* Never modify generated files; modify the sources that generate them instead.
+* New behavior must be documented through tests.
+
+

Wurstpack/wurstscript/grill

@@ -1,3 +1,28 @@
-#!/bin/bash
+#!/usr/bin/env bash
+set -euo pipefail
 
-java -jar ~/.wurst/WurstSetup.jar ${@:1:6}
+RUNTIME="$HOME/.wurst/wurst-runtime/bin/java"
+
+# Resolve script dir (absolute)
+DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+JAR="$DIR/grill/grill.jar"
+if [[ ! -f "$JAR" ]]; then
+  JAR="$DIR/../grill/grill.jar"
+fi
+
+if [[ ! -f "$JAR" ]]; then
+  echo "[grill] ERROR: Missing jar. Searched:"
+  echo "  $DIR/grill/grill.jar"
+  echo "  $DIR/../grill/grill.jar"
+  exit 2
+fi
+
+if [[ ! -x "$RUNTIME" ]]; then
+  echo "[grill] ERROR: Bundled runtime not found or not executable at:"
+  echo "  $RUNTIME"
+  echo "Please reinstall wurstscript via the VSCode extension."
+  exit 3
+fi
+
+exec "$RUNTIME" -jar "$JAR" "$@"