Skip to content

Latest commit

 

History

History
189 lines (123 loc) · 4.69 KB

AGENTS.md

File metadata and controls

189 lines (123 loc) · 4.69 KB

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). 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.