Skip to content

AGENTS.md

Latest commit

 

History

History
167 lines (112 loc) · 4.18 KB

AGENTS.md

File metadata and controls

167 lines (112 loc) · 4.18 KB

AGENTS.md - Drupal Toolkit Plugin Development Guide

Project Overview

This is a JetBrains IntelliJ Platform plugin (PHPStorm/WebStorm) for Drupal project maintainers. Written in Kotlin, built with Gradle (Kotlin DSL).

Build Commands

Full Build & Test

cd drupal-toolkit
./gradlew buildPlugin      # Build the plugin distribution
./gradlew check            # Run all tests + verification
./gradlew verifyPlugin     # Verify plugin structure

Running Tests

./gradlew test                              # Run all tests
./gradlew test --tests "MyPluginTest"       # Run specific test class
./gradlew test --tests "MyPluginTest.testXMLFile"  # Run single test method

Code Quality

./gradlew qodana     # Run Qodana static analysis (or use qodana.yml config)
./gradlew kover      # Generate code coverage report

Running the Plugin Locally

./gradlew runIde     # Run IDE with plugin installed (uses Run Plugin.run.xml)

Code Style Guidelines

General Conventions

  • Language: Kotlin (JVM 21)
  • Build System: Gradle with Kotlin DSL (*.gradle.kts)
  • Package: com.github.drupaltools.drupaltoolkit

Imports

  • Follow standard Kotlin import ordering (stdlib → external → internal)
  • Use explicit imports; avoid wildcard imports except for stdlib

Formatting

  • 4 spaces for indentation (IntelliJ default for Kotlin)
  • Follow Kotlin idiomatic style (use expression bodies where appropriate)
  • Max line length: 120 characters (IntelliJ default)

Naming Conventions

  • Classes/Objects: PascalCase (MyPluginTest, MyProjectService)
  • Functions/Properties: camelCase (testXMLFile, getRandomNumber)
  • Constants: UPPER_SNAKE_CASE
  • Packages: lowercase with dots

Types

  • Use explicit types for public APIs
  • Type inference acceptable for local variables
  • Nullable types: String? (not String!)
  • Use val by default, var only when mutation is needed

Error Handling

  • Use Kotlin's try-catch for recoverable errors
  • Use assert* methods from test framework for assertions
  • Avoid empty catch blocks

Testing

  • Extend BasePlatformTestCase from IntelliJ Platform
  • Use @TestDataPath annotation for test data files
  • Test files go in src/test/kotlin/
  • Test data goes in src/test/testData/

Plugin Structure

  • Plugin XML: src/main/resources/META-INF/plugin.xml
  • Services: src/main/kotlin/.../services/
  • Tool Windows: src/main/kotlin/.../toolWindow/
  • Startup: src/main/kotlin/.../startup/

Architecture Patterns

Services (Dependency Injection)

// Register in plugin.xml or via @Service annotation
class MyProjectService : ProjectService {
    fun getRandomNumber(): Int = Random.nextInt()
}

// Usage in tests
val projectService = project.service<MyProjectService>()

Tool Windows

  • Implement ToolWindowFactory
  • Register in plugin.xml with toolWindow extension point

Extension Points

  • Register extensions in plugin.xml (actions, listeners, etc.)

IDE Configuration

Recommended IDE Setup

  • IntelliJ IDEA 2025.2+ (matches platformVersion)
  • Kotlin plugin enabled
  • Java 21 SDK configured

Run Configurations (.run/)

  • Run Plugin.run.xml - Run IDE with plugin
  • Run Tests.run.xml - Run tests
  • Run Verifications.run.xml - Run plugin verifier

CI/CD (GitHub Actions)

The build workflow (.github/workflows/build.yml) runs:

  1. buildPlugin - Creates distribution
  2. check - Tests + verification
  3. qodana - Static analysis
  4. verifyPlugin - IntelliJ Plugin Verifier

Key Dependencies

  • IntelliJ Platform: 2025.2.5 (platformVersion in gradle.properties)
  • Kotlin: Via Gradle version catalog (gradle/libs.versions.toml)
  • Testing: opentest4j, junit

File Locations

Purpose Path
Main source src/main/kotlin/
Test source src/test/kotlin/
Resources src/main/resources/
Gradle config build.gradle.kts
Properties gradle.properties
Version catalog gradle/libs.versions.toml