Contributing Guide

Thank you for your interest in contributing to the ReScript IntelliJ Plugin!

Prerequisites

Requirement	Version	Notes
JDK	21+	Required by IntelliJ Platform 2025.3+
Node.js	18+	Required for LSP server and .d.ts binding generation
IntelliJ IDEA	2025.3+	Community or Ultimate edition
Gradle	9.4+	Wrapper included — no manual install needed

Getting Started

1. Fork the repository on GitHub

2. Clone your fork:

   git clone https://github.com/<your-username>/rescript-intellij-plugin.git
   

3. Set up your development environment

4. Create a feature branch:

   git checkout -b feature/my-feature
   

Development Workflow

Branch Naming

Prefix	Use
feature/	New features
fix/	Bug fixes
refactor/	Code refactoring
docs/	Documentation
test/	Test additions
chore/	Configuration, dependencies

Commit Messages

Use emoji prefixes for commit messages:

Emoji	Use
✨	New feature
🐛	Bug fix
♻️	Refactoring
📝	Documentation
🎨	UI/style improvement
⚡	Performance improvement
🔧	Configuration change
✅	Test addition/fix
🗑️	Code deletion

Format: <emoji> <verb> <concise description>

Examples:

• ✨ Add JSX token support to lexer

• 🐛 Fix nested comment parsing

• 📝 Update architecture documentation

Code Conventions

Language

• All source code is written in Kotlin

• Lexer definition is in JFlex (generates Java)

Package Structure

All classes go under com.rescript.plugin.*, organized by feature:

com.rescript.plugin.highlight/   # Syntax highlighting
com.rescript.plugin.lsp/         # LSP integration
com.rescript.plugin.navigation/  # Navigation features
...

Code Style

• ktlint is enforced via CI (./gradlew ktlintCheck)

• Auto-fix: ./gradlew ktlintFormat

• IntelliJ’s built-in Kotlin formatter generally matches ktlint

KDoc Comments

All classes and significant methods must have KDoc comments in English:

/**
 * Provides code folding for ReScript files.
 *
 * Recognizes multi-line declarations, block comments,
 * and custom //#region markers.
 *
 * @see RescriptCustomFoldingProvider for region-based folding
 */
class RescriptFoldingBuilder : CustomFoldingBuilder() {
    /**
     * Builds fold regions for the given PSI element.
     *
     * @param root the root PSI element to scan
     * @param descriptors list to add fold descriptors to
     * @param document the document being folded
     */
    override fun buildLanguageFoldRegions(...) { ... }
}

Testing

• Every code change must have corresponding tests

• Test file naming: <ClassName>Test.kt

• Tests mirror the source package structure

• See the Testing Guide for details

AI-Assisted Development

This project uses structured workflows for AI-assisted development with Claude Code. The following configuration files define the development process:

• .claude/rules/steering-workflow.md — Steering workflow requiring requirements.md, design.md, and tasklist.md before implementation

• .claude/rules/definition-of-done.md — 5-phase Definition of Done (Planning → Implementation → Pre-commit → Pre-merge → Post-merge)

• .claude/rules/git-conventions.md — Git worktree isolation for feature branches, emoji commit prefixes, and branch naming conventions

Steering documents are stored in .steering/[YYYYMMDD]-[NNN]-[title]/ directories and committed alongside code changes.

Quality Checks

The project enforces several automated quality gates via CI and custom Gradle tasks:

Check	Command	Description
Code style	./gradlew ktlintCheck	Kotlin linting (auto-fix: ./gradlew ktlintFormat)
KDoc comments	./gradlew checkKdoc	All classes must have KDoc comments
Test files	./gradlew checkTestFiles	Production classes must have corresponding tests
EP registration	./gradlew checkExtensionPointRegistration	plugin.xml must reference existing classes
Coverage	./gradlew koverHtmlReport	Report at build/reports/kover/html/index.html
Coverage threshold	./gradlew koverVerify	Minimum 85% line coverage enforced

Submitting Changes

1. Run the full CI check locally:

   ./gradlew ktlintCheck buildPlugin test koverHtmlReport
   

2. Verify the build and all tests pass

3. Check code coverage for new code:

   open build/reports/kover/html/index.html
   

4. Push your branch and create a Pull Request

PR Guidelines

• Keep PRs focused on a single feature or fix

• Write a clear description of what changed and why

• Include screenshots for UI changes

• Reference related issues if applicable

Questions?

• Open an issue on GitHub

• Check existing issues and discussions