Skip to content

CLAUDE.md

Latest commit

 

History

History
65 lines (43 loc) · 3.49 KB

CLAUDE.md

File metadata and controls

65 lines (43 loc) · 3.49 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Plugin Does

An IntelliJ Platform plugin for KStateMachine. It statically analyzes Kotlin source files to extract state machine definitions, states, and transitions defined with the KStateMachine DSL, then displays findings in a tool window. Currently in early development — the parser is functional but visualization is still log-based.

Build & Test Commands

# Build the plugin ZIP
./gradlew buildPlugin

# Run tests
./gradlew test

# Run in a sandboxed IDE instance
./gradlew runIde

# Verify plugin structure against IntelliJ guidelines
./gradlew verifyPlugin

# Code coverage report (Kover)
./gradlew koverReport

# Code quality inspection (Qodana)
./gradlew qodanaAnalyze

Run a single test class:

./gradlew test --tests "com.github.nsk90.kstatemachineintellijplatformplugin.MyPluginTest"

Architecture

The plugin has four layers:

Model (model/) — Plain data classes: StateMachine (extends State), State, Transition. These are the output of parsing.

Parser (psi/PsiElementsParser.kt) — The core logic. Traverses Kotlin PSI trees using IntelliJ's binding context to resolve fully-qualified function names, then matches against KStateMachine's creation functions (createStateMachine, createStateMachineBlocking, etc.), state factory functions (state(), initialState(), dataState(), etc.), and transition functions (transition(), transitionOn(), etc.). All recognized function names are defined as constants at the top of the file grouped by ru.nsk.kstatemachine.* package paths. The import-aware detection (added recently) is what makes matching reliable.

Service (services/FileSwitchService.kt) — A project-level service that wraps a MutableSharedFlow and emits events when the user switches editor tabs.

Tool Window (toolWindow/MainToolWindowFactory.kt) — Subscribes to FileSwitchService, runs the parser in a background ProgressTask, and writes results to a log text area. Uses a coroutine scope that is cancelled on disposal.

IntelliJ Platform Details

  • Target platform: IntelliJ Ultimate (IU) 2026.2.1; compatible range 262–262.* (2026.1 dropped in 0.3.0: its older JCEF lacks the CefResourceHandler.open/read/skip API that 2026.2 requires — see PlantUmlJsRenderer.BundledResourceHandler)
  • Platform version and build range live in gradle.properties (platformVersion, pluginSinceBuild, pluginUntilBuild). When bumping them, also update the compatibility badge and "Compatibility" line in README.md.
  • Declared plugin dependencies: com.intellij.modules.platform, com.intellij.java, org.jetbrains.kotlin
  • Plugin descriptor: src/main/resources/META-INF/plugin.xml
  • Localized strings: src/main/resources/messages/MyBundle.properties + MyBundle.kt wrapper

When adding new extension points (tool windows, actions, services), register them in plugin.xml.

Key Conventions

  • When adding new KStateMachine function names to detect, add them to the constant sets at the top of PsiElementsParser.kt (not inline in the parsing logic).
  • PSI traversal uses KtCallExpression and binding context for FQN resolution — prefer this pattern over string-matching import statements.
  • Background work in the tool window uses object : Task.Backgroundable(project, ...) { override fun run(...) } with ApplicationManager.invokeLater for any UI updates.