JetBrains IDEのプラグインRailroadsをIDE 2025.2バージョンに対応したときのまとめ

JetBrains IntelliJ Platform Plugin Railroads plugin

自分の開発しているJetBrains IDEのプラグインRailoradsについて、IntelliJ IDEAとRubyMineで2025.2系からエラーが出るようになりました。
Exception thrown in IntelliJ 2025.2 with latest Ruby plugin version · Issue #60 · thinkAmi/railroads

先日、Railroadsを2025.2系へと対応したことから、その時の作業内容をメモとして残しておきます。

　
目次

　

RubyProjectAndLibrariesScopeが使えなくなった

Railroadsプラグインでは、Program Structure Interface(PSI)を使ってルーティングからControllerへのコードジャンプを実現しています。

PSIとは、IntelliJ Platform Plugin SDKが提供する、ソースコードを解析・操作するためのAPIです。プログラミング言語の抽象構文木（AST: Abstract Syntax Tree）に近い概念を表現するAPIです。

　
Railroads 0.3.0までは

val scope = RubyProjectAndLibrariesScope(project)

のようにすることで、Railsのクラスやモジュール情報を取得していました。

しかし、バージョン2025.2から RubyProjectAndLibrariesScopeが使えなくなってしまい、エラーが出るようになってしまいました。

java.lang.IllegalAccessError: class com.github.thinkami.railroads.helper.PsiUtil$Companion tried to access method 'void org.jetbrains.plugins.ruby.ruby.lang.psi.RubyProjectAndLibrariesScope.(com.intellij.openapi.project.Project)'

　
破壊的な変更があったのだろうかと、公式ドキュメントの互換性のページを確認しましたが、それらしい記載はありませんでした。
Incompatible Changes in IntelliJ Platform and Plugins API 2025.* | IntelliJ Platform Plugin SDK

　
代替機能がないかをClaudeにきいてみたところ GlobalSearchScope が使えるとのことでした。公式ドキュメントにはそれらしい記載はないものの、

val scope = GlobalSearchScope.allScope(project)

とすることで、同等の結果が得られました。

　
また、この修正に伴い

if (item is RClass) {
    name = item.qualifiedName
} else if (item is RModule) {
    name = item.qualifiedName
}

がコンパイルエラーになったことから、ここも修正することにしました。

fqn.fullPath だとRails自身が持っているルーティングのコードジャンプができなくなったことから、 fqnWithNesting.fullPathを使うことにしました。

　
他にも controllerClass.qualifiedName を使っていたところを、同様に controllerClass.fqnWithNesting.fullPathへと修正しました。

　

plugin.xmlでcom.intellij.modules.rubyを指定してもverifyPluginが失敗するようになった

公式ドキュメントを読むと、RubyMine (Rubyプラグイン)で動作するプラグインを作るには

  • plugin.xml で com.intellij.modules.rubyを指定する
  • build.gradle.ktで org.jetbrains.plugins.rubyを指定する

との記載がありました。

　
今まではこの指定で動いていたのですが、IDE 2025.2系で動かそうとすると、Gradleの verifyPluginタスクで以下のエラーが出るようになりました。

Plugin com.github.thinkami.railroads:0.4.0 against IU-252.26830.24: 1 missing mandatory dependency. 2 possible compatibility problems, some of which may be caused by absence of dependency in the target IDE IU-252.26830.24
Missing dependencies: 
    module com.intellij.modules.ruby: Unavailable
Compatibility problems (2): 
    #Package 'org.jetbrains.plugins.ruby' is not found
        Package 'org.jetbrains.plugins.ruby' is not found along with its 17 classes.
        Probably the package 'org.jetbrains.plugins.ruby' belongs to a library or dependency that is not resolved by the checker.
        It is also possible, however, that this package was actually removed from a dependency causing the detected problems. Access to unresolved classes at runtime may lead to **NoSuchClassError**.

　
試しに、 plugin.xmlに org.jetbrains.plugins.rubyを指定したところ、verifyPluginタスクが正常終了しました。そのため、 plugin.xmlの設定を変更すれば動くことが分かりました。ただ、この内容は公式ドキュメントと異なるため、この対応でよいのか悩みました。

そこで、他にもRubyプラグインに依存しているプラグインではどのような修正をしているかを調べてみることにしました。すると、以下のパターンがあることが分かりました。

　
YouTrackを見てみましたが、 plugin.xmlの dependsまわりのissueはいくつかあったものの、今回のものに該当するようなものではなさそうでした。

　
リリースノートもながめてみましたが、それらしいものは記載されていませんでした。
Release Notes | Knowledge Base

　
どのように対応するか悩みましたが、いったんはドキュメントを信じてみようということで、

  • plugin.xmlで com.intellij.modules.rubyを指定
  • build.gradle.ktの dependencies では rubymine("2025.1")のようにRubyMineを指定

という方針に決めました。

そこで、 build.gradle.kt の dependencies について以下を設定しました。

  • ローカルにあるIDEの実機で動作確認するときは、そのIDEを使う
  • それ以外の場合は、RubyMineの最低対応バージョンを使う
    • テストコードの実行時もこちら

この修正を行ったところ、verifyPluginタスクも正常終了するようになりました。

dependencies {  
    intellijPlatform {  
        val isTestTask = gradle.startParameter.taskNames.any {  
            it.contains("test", ignoreCase = true)  
        }
  
        if (prop != null && !isTestTask) {
            prop.getProperty("ideDir")?.let { ideDirValue ->
                if (ideDirValue.isNotEmpty()) {
                    local(file(ideDirValue))
                }
            }
        } else {  
            rubymine(providers.gradleProperty("platformVersion"))
        }

　

untilBuildの指定が必要になった

こちらはIDE 2025.2というよりも、ビルドで使う IntelliJ Platform Gradle Plugin 2.xの影響です。

　
今までRailroadsでは「IDEがリリースされるたびにメンテナンスが必要になる」ことを避けるため、プラグインの対応しているバージョン範囲を untilBuildで指定しませんでした。

しかし、IntelliJ Platform Gradle Plugin 2.xを使うようになってから、 untilBuildの指定が必要になったようでした。

それでも untilBuildを指定しなくて良い方法がないかを調べたところ、以下のissueに記載がありました。
v2: No IDE resolved for verification with the IntelliJ Plugin Verifier · Issue #1717 · JetBrains/intellij-platform-gradle-plugin

そこで、Railroadsの untilBuildに対し、issueにあった定義を移植しました。

untilBuild = providers.gradleProperty("pluginUntilBuild").takeIf {
    !it.orNull.isNullOrBlank()
} ?: provider { null }

　

JetBrains MarketplaceでverifyPluginがfailした

GitHub Actionsによる verifyPlugin が成功したことから、GitHub ActionsでRailroadsをpublishしました。

GitHub ActionsがパスしているからJetBrains MarketplaceのCIもパスするだろうと考えていましたが、実際のところはfailしました。GitHub ActionsとJetBrains Marketplaceでは、同じ intellij-plugin-verifierのバージョン 1.395を使っているようでしたが、差が出てしまいました。

　
さすがに原因が分からなかったので似たような事例を探したところ、最近の verifyPluginのバージョンのせいなのか、failする事例がいくつかありました。

　
ここで、JetBrainsから届いたメールに

The Plugin Verifier found potential compatibility issues with this update. Please review the details on your plugin versions page and make sure your plugin is fully compatible with the products and version range you’ve specified.

If you think any of these issues are false positives, please reply to this email.

と書かれていることに気づきました。もしかしたらfalse positivesかもしれないと考え、Plugin Verifierの状況として

  • ローカルではパスする
  • GItHub Actionsでもパスする
  • JetBrains Marketplaceのうち、Verifierが IDE だったり、手動で動かしたRubyMineはパスする

を伝えたところ、無事に公開されました。

　

細かな保守作業

IDE 2025.2系対応とは関係ないのですが、保守作業として以下も行いました。

　

IntelliJ Platform Gradle Pluginのバージョンを上げた

今回の保守のついでに、IntelliJ Platform Gradle Pluginのバージョンを上げることにしました。

2025/10/09時点では最新バージョンは2.9.0です。
JetBrains/intellij-platform-gradle-plugin: Gradle plugin for building plugins for JetBrains IDEs

ただ、2.9.0だと手元では verifyPlugin がうまく動かなかったことから、issueを探したところ似たような事例がありました。
"No IDE resolved for verification with the IntelliJ Plugin Verifier" with 2.9.0 · Issue #2025 · JetBrains/intellij-platform-gradle-plugin

そこで今回は、 2.8.0へのアップデートにとどめました。

　

intellij-platform-plugin-templateのファイルを移植

Railroadsのベースとして intellij-platform-plugin-template を使っています。
JetBrains/intellij-platform-plugin-template: Template repository for creating plugins for IntelliJ Platform

　
このテンプレートリポジトリも日々更新されていることから、Railroadsが利用した時の状態と現在のmainブランチではそこそこ差があります。

特に、GitHub Actionsが内部で使っていたJavaのバージョンが 17であり、これはIDE 2024.2以降のPlatformのJavaバージョン (21)とは異なっていることが気になっていました。
https://plugins.jetbrains.com/docs/intellij/build-number-ranges.html#platformVersions

　
ではどのバージョンに上げるのが適切なのかを調べたところ、2025/10時点でのChangelogに

Update minimal supported Gradle version to 8.13

https://github.com/JetBrains/intellij-platform-gradle-plugin/blob/main/CHANGELOG.md

との記載がありました。

そこで、今回はGradle 8.14.3へとバージョンアップしたときのコミット 08d83f4 時点のファイルをRailroadsへと移植しました。

　

KotestのテストコードをJUnit4のテストコードへと修正

元々興味本位で Kotest でテストを書いていました。ただ、メンテナンスをする中で、できる限り依存の少ない状態のほうが各種アップデートが楽だと実感しました。

そこで、今回を機に、KotestのテストコードをJUnit4のテストコードへと修正しました。

　

ソースコード

RailroadsのソースコードはGitHubで公開しています。
https://github.com/thinkAmi/railroads

また、IDE 2025.2へ対応したときのプルリクはこちらです。
https://github.com/thinkAmi/railroads/pull/63