Merge pull request #321 from mercari/improve-jetbrains-plugin

feat(jetbrains-plugin): add semantic tokens support and enhance import path configuration UI

Author: utahta

lsp/client/jetbrains/.gitignore

@@ -2,3 +2,5 @@
 .idea
 .qodana
 build
+.intellijPlatform
+.kotlin

lsp/client/jetbrains/CHANGELOG.md

@@ -3,3 +3,45 @@
 # gRPC Federation Changelog
 
 ## [Unreleased]
+
+### Added
+- New list-based UI for Proto Import Paths configuration
+- Enable/disable toggle for individual import paths
+- File browser dialog for adding and editing paths
+- Path validation feature to check if directories exist
+- Variable expansion support for `~/` and `${PROJECT_ROOT}`
+- Toolbar buttons for add, remove, and reorder operations
+- "Validate Paths" button to verify all configured paths
+- Semantic tokens support for enhanced syntax highlighting of gRPC Federation annotations
+  - Token type mappings for proper colorization of proto elements
+  - Explicit semantic tokens request for proto files
+
+### Changed
+- Redesigned settings interface from single text field to table-based UI
+- Improved path management with better visual feedback
+- Enhanced user experience for managing multiple import paths
+- Migrated settings storage format from simple string list to structured entries with enable/disable state
+- Updated to IntelliJ Platform Gradle Plugin 2.7.2 (latest)
+- Updated to Platform Version 2024.3.3 with Kotlin 2.1.0
+- Updated JVM toolchain from Java 17 to Java 21 (recommended for 2024.3.3)
+- Changed LSP server descriptor from ProjectWideLspServerDescriptor to LspServerDescriptor for proper semantic tokens support
+
+### Fixed
+- Issue with paths containing spaces in the previous text field approach
+- Better handling of empty and invalid path entries
+- Checkbox display issue in the Enabled column with explicit renderer and editor
+- Diagnostic messages containing HTML tags (like `<input>`) are now properly escaped to prevent UI rendering issues
+
+### Deprecated
+- `importPaths` field in settings storage (will be removed in v0.3.0)
+  - Automatic migration: Existing configurations will be automatically converted to the new format
+  - The plugin maintains backward compatibility by reading from both old and new formats
+  - Only the new `importPathEntries` format will be supported from v0.3.0 onwards
+
+## [0.1.0]
+
+### Added
+- Initial release of gRPC Federation IntelliJ plugin
+- Basic Language Server Protocol (LSP) integration
+- Proto import paths configuration
+- Support for `.proto` files with gRPC Federation annotations

lsp/client/jetbrains/README.md

@@ -1,28 +1,90 @@
 <!-- Plugin description -->
 # gRPC Federation Language Server for JetBrains
-The gRPC Federation Language Server for JetBrains is a plugin designed for JetBrains IDEs to integrate with the gRPC Federation language server, offering various useful functionalities such as code completion.
+
+The gRPC Federation Language Server for JetBrains is a plugin designed for JetBrains IDEs to integrate with the gRPC Federation language server, providing enhanced development experience for Protocol Buffer files with gRPC Federation annotations.
 
 ## Features
 
-Currently, the following features are supported:
+- **Go to Definition** - Navigate to proto message and field definitions
+- **Diagnostics** - Real-time error detection and validation
+- **Code Completion** - Intelligent suggestions for gRPC Federation annotations
+
+## Requirements
 
-- Goto Definition
-- Diagnostics
-- Code Completion
+- **IntelliJ IDEA Ultimate** 2023.3 or newer (This plugin requires Ultimate Edition)
+- **grpc-federation-language-server** installed and available in PATH
 
 ## Installation
-To utilize the plugin, `grpc-federation-language-server` must be accessible in the path. If Go is available, execute the following command to install it:
+
+### Step 1: Install the Language Server
+The plugin requires `grpc-federation-language-server` to be accessible in the system PATH. If Go is available, install it with:
 
 ```console
 $ go install github.com/mercari/grpc-federation/cmd/grpc-federation-language-server@latest
 ```
 
-Afterward, install the plugin from the Marketplace.
+Verify the installation:
+```console
+$ which grpc-federation-language-server
+```
+
+### Step 2: Install the Plugin
+Install the plugin from JetBrains Marketplace:
 
-`Settings/Preferences` > `Plugins` > `Marketplace` > `Search for "gRPC Federation"` > `Install`
+1. Open **Settings/Preferences** → **Plugins**
+2. Select **Marketplace** tab
+3. Search for **"gRPC Federation"**
+4. Click **Install** and restart the IDE
 
 ## Configuration
-For `grpc-federation-language-server` to function properly, provide proto import paths to import dependent proto files.
 
-`Settings/Preferences` > `Tools` > `gRPC Federation` > `Proto Import Paths`
+### Setting Import Paths
+Configure proto import paths for the language server to resolve dependencies:
+
+1. Navigate to **Settings/Preferences** → **Tools** → **gRPC Federation**
+2. In the **Proto Import Paths** section:
+   - Click **+** to add a new path
+   - Use the file browser to select directories
+   - Enable/disable paths using checkboxes
+   - Reorder paths using ↑/↓ buttons
+   - Click **Validate Paths** to verify all directories exist
+
+### Supported Path Variables
+
+- `~/` - User's home directory
+- `${PROJECT_ROOT}` - Current project root directory
+
+Example paths:
+```
+/usr/local/include
+${PROJECT_ROOT}/proto
+~/workspace/shared-protos
+```
+
+## Troubleshooting
+
+### Language Server Not Found
+If you see "grpc-federation-language-server not found" error:
+1. Ensure the language server is installed (see Installation section)
+2. Check if it's in your PATH: `which grpc-federation-language-server`
+3. Restart the IDE after installation
+
+### Proto Files Not Recognized
+If proto files are not being analyzed:
+1. Ensure the file extension is `.proto`
+2. Check that import paths are correctly configured
+3. Validate paths using the **Validate Paths** button
+4. Check the IDE logs: **Help** → **Show Log in Finder/Explorer**
+
+### Import Resolution Issues
+If imports are not being resolved:
+1. Add all necessary proto directories to import paths
+2. Ensure paths are in the correct order (more specific paths first)
+3. Check that all proto dependencies are available
+
+## Support
+
+- **Issues**: [GitHub Issues](https://github.com/mercari/grpc-federation/issues)
+- **Documentation**: [gRPC Federation Documentation](https://github.com/mercari/grpc-federation)
+
 <!-- Plugin description end -->

lsp/client/jetbrains/build.gradle.kts

@@ -1,13 +1,14 @@
 import org.jetbrains.changelog.Changelog
 import org.jetbrains.changelog.markdownToHTML
+import org.jetbrains.intellij.platform.gradle.TestFrameworkType
 
 fun properties(key: String) = providers.gradleProperty(key)
 fun environment(key: String) = providers.environmentVariable(key)
 
 plugins {
     id("java") // Java support
     alias(libs.plugins.kotlin) // Kotlin support
-    alias(libs.plugins.gradleIntelliJPlugin) // Gradle IntelliJ Plugin
+    alias(libs.plugins.gradleIntelliJPlugin) // Gradle IntelliJ Platform Plugin
     alias(libs.plugins.changelog) // Gradle Changelog Plugin
     alias(libs.plugins.qodana) // Gradle Qodana Plugin
     alias(libs.plugins.kover) // Gradle Kover Plugin
@@ -19,66 +20,54 @@ version = properties("pluginVersion").get()
 // Configure project's dependencies
 repositories {
     mavenCentral()
+    
+    // IntelliJ Platform Gradle Plugin Repositories Extension - read more: https://plugins.jetbrains.com/docs/intellij/tools-intellij-platform-gradle-plugin-repositories-extension.html
+    intellijPlatform {
+        defaultRepositories()
+    }
 }
 
 // Dependencies are managed with Gradle version catalog - read more: https://docs.gradle.org/current/userguide/platforms.html#sub:version-catalog
 dependencies {
 //    implementation(libs.annotations)
+
+    // IntelliJ Platform Gradle Plugin Dependencies Extension - read more: https://plugins.jetbrains.com/docs/intellij/tools-intellij-platform-gradle-plugin-dependencies-extension.html
+    intellijPlatform {
+        create(properties("platformType"), properties("platformVersion"))
+        
+        // Plugin Dependencies. Uses `platformPlugins` property from the gradle.properties file.
+        bundledPlugins(properties("platformPlugins").map { it.split(',').map(String::trim).filter(String::isNotEmpty) })
+        
+        pluginVerifier()
+        zipSigner()
+        testFramework(TestFrameworkType.Platform)
+    }
 }
 
 // Set the JVM language level used to build the project.
 kotlin {
-    jvmToolchain(17)
-}
-
-// Configure Gradle IntelliJ Plugin - read more: https://plugins.jetbrains.com/docs/intellij/tools-gradle-intellij-plugin.html
-intellij {
-    pluginName = properties("pluginName")
-    version = properties("platformVersion")
-    type = properties("platformType")
-
-    // Plugin Dependencies. Uses `platformPlugins` property from the gradle.properties file.
-    plugins = properties("platformPlugins").map { it.split(',').map(String::trim).filter(String::isNotEmpty) }
+    jvmToolchain(21)
 }
 
-// Configure Gradle Changelog Plugin - read more: https://github.com/JetBrains/gradle-changelog-plugin
-changelog {
-    groups.empty()
-    repositoryUrl = properties("pluginRepositoryUrl")
-}
-
-// Configure Gradle Kover Plugin - read more: https://github.com/Kotlin/kotlinx-kover#configuration
-koverReport {
-    defaults {
-        xml {
-            onCheck = true
-        }
-    }
-}
-
-tasks {
-    wrapper {
-        gradleVersion = properties("gradleVersion").get()
-    }
-
-    patchPluginXml {
+// Configure IntelliJ Platform Gradle Plugin - read more: https://plugins.jetbrains.com/docs/intellij/tools-intellij-platform-gradle-plugin-extension.html
+intellijPlatform {
+    pluginConfiguration {
         version = properties("pluginVersion")
-        sinceBuild = properties("pluginSinceBuild")
-        untilBuild = properties("pluginUntilBuild")
-
+        name = properties("pluginName")
+        
         // Extract the <!-- Plugin description --> section from README.md and provide for the plugin's manifest
-        pluginDescription = providers.fileContents(layout.projectDirectory.file("README.md")).asText.map {
+        description = providers.fileContents(layout.projectDirectory.file("README.md")).asText.map {
             val start = "<!-- Plugin description -->"
             val end = "<!-- Plugin description end -->"
-
+            
             with (it.lines()) {
                 if (!containsAll(listOf(start, end))) {
                     throw GradleException("Plugin description section not found in README.md:\n$start ... $end")
                 }
                 subList(indexOf(start) + 1, indexOf(end)).joinToString("\n").let(::markdownToHTML)
             }
         }
-
+        
         val changelog = project.changelog // local variable for configuration cache compatibility
         // Get the latest available change notes from the changelog file
         changeNotes = properties("pluginVersion").map { pluginVersion ->
@@ -91,29 +80,57 @@ tasks {
                 )
             }
         }
+        
+        ideaVersion {
+            sinceBuild = properties("pluginSinceBuild")
+            untilBuild = properties("pluginUntilBuild")
+        }
     }
-
-    // Configure UI tests plugin
-    // Read more: https://github.com/JetBrains/intellij-ui-test-robot
-    runIdeForUiTests {
-        systemProperty("robot-server.port", "8082")
-        systemProperty("ide.mac.message.dialogs.as.sheets", "false")
-        systemProperty("jb.privacy.policy.text", "<!--999.999-->")
-        systemProperty("jb.consents.confirmation.enabled", "false")
+    
+    publishing {
+        token = environment("PUBLISH_TOKEN")
+        // The pluginVersion is based on the SemVer (https://semver.org) and supports pre-release labels, like 2.1.7-alpha.3
+        // Specify pre-release label to publish the plugin in a custom Release Channel automatically. Read more:
+        // https://plugins.jetbrains.com/docs/intellij/deployment.html#specifying-a-release-channel
+        channels = properties("pluginVersion").map { listOf(it.substringAfter('-', "").substringBefore('.').ifEmpty { "default" }) }
     }
-
-    signPlugin {
+    
+    signing {
         certificateChain = environment("CERTIFICATE_CHAIN")
         privateKey = environment("PRIVATE_KEY")
         password = environment("PRIVATE_KEY_PASSWORD")
     }
+    
+    pluginVerification {
+        ides {
+            recommended()
+        }
+    }
+}
 
+// Configure Gradle Changelog Plugin - read more: https://github.com/JetBrains/gradle-changelog-plugin
+changelog {
+    groups.empty()
+    repositoryUrl = properties("pluginRepositoryUrl")
+}
+
+// Configure Gradle Kover Plugin - read more: https://github.com/Kotlin/kotlinx-kover#configuration
+kover {
+    reports {
+        filters {
+            excludes {
+                // Exclude generated code and build files if needed
+            }
+        }
+    }
+}
+
+tasks {
+    wrapper {
+        gradleVersion = properties("gradleVersion").get()
+    }
+    
     publishPlugin {
         dependsOn("patchChangelog")
-        token = environment("PUBLISH_TOKEN")
-        // The pluginVersion is based on the SemVer (https://semver.org) and supports pre-release labels, like 2.1.7-alpha.3
-        // Specify pre-release label to publish the plugin in a custom Release Channel automatically. Read more:
-        // https://plugins.jetbrains.com/docs/intellij/deployment.html#specifying-a-release-channel
-        channels = properties("pluginVersion").map { listOf(it.substringAfter('-', "").substringBefore('.').ifEmpty { "default" }) }
     }
-}
+}

lsp/client/jetbrains/gradle.properties

@@ -1,25 +1,31 @@
 # IntelliJ Platform Artifacts Repositories -> https://plugins.jetbrains.com/docs/intellij/intellij-artifacts.html
 
 pluginGroup = com.github.mercari.grpcfederation
-pluginName = grpc-federation
+pluginName = gRPC Federation
 pluginRepositoryUrl = https://github.com/mercari/grpc-federation
 # SemVer format -> https://semver.org
-pluginVersion = 0.1.0
+pluginVersion = 0.2.0
 
 # Supported build number ranges and IntelliJ Platform versions -> https://plugins.jetbrains.com/docs/intellij/build-number-ranges.html
-pluginSinceBuild = 233
-pluginUntilBuild = 241.*
+pluginSinceBuild = 243
+# pluginUntilBuild is intentionally not set to allow the plugin to be compatible with future IDE versions.
+# This is relatively safe because:
+# 1. This plugin uses stable LSP (Language Server Protocol) APIs which are unlikely to break
+# 2. The plugin has minimal IDE integration surface area
+# 3. Users can install and test on newer versions without waiting for plugin updates
+# If compatibility issues arise in future versions, we can add the restriction then.
+pluginUntilBuild = 
 
 # IntelliJ Platform Properties -> https://plugins.jetbrains.com/docs/intellij/tools-gradle-intellij-plugin.html#configuration-intellij-extension
 platformType = IU
-platformVersion = 2023.3.5
+platformVersion = 2024.3.3
 
 # Plugin Dependencies -> https://plugins.jetbrains.com/docs/intellij/plugin-dependencies.html
 # Example: platformPlugins = com.intellij.java, com.jetbrains.php:203.4449.22
 platformPlugins =
 
 # Gradle Releases -> https://github.com/gradle/gradle/releases
-gradleVersion = 8.6
+gradleVersion = 8.10
 
 # Opt-out flag for bundling Kotlin standard library -> https://jb.gg/intellij-platform-kotlin-stdlib
 kotlin.stdlib.default.dependency = false

lsp/client/jetbrains/gradle/libs.versions.toml

@@ -3,18 +3,18 @@
 annotations = "24.1.0"
 
 # plugins
-kotlin = "1.9.23"
-changelog = "2.2.0"
-gradleIntelliJPlugin = "1.17.2"
-qodana = "2023.3.1"
-kover = "0.7.6"
+kotlin = "2.1.0"
+changelog = "2.2.1"
+gradleIntelliJPlugin = "2.7.2"
+qodana = "2024.2.5"
+kover = "0.8.3"
 
 [libraries]
 annotations = { group = "org.jetbrains", name = "annotations", version.ref = "annotations" }
 
 [plugins]
 changelog = { id = "org.jetbrains.changelog", version.ref = "changelog" }
-gradleIntelliJPlugin = { id = "org.jetbrains.intellij", version.ref = "gradleIntelliJPlugin" }
+gradleIntelliJPlugin = { id = "org.jetbrains.intellij.platform", version.ref = "gradleIntelliJPlugin" }
 kotlin = { id = "org.jetbrains.kotlin.jvm", version.ref = "kotlin" }
 kover = { id = "org.jetbrains.kotlinx.kover", version.ref = "kover" }
 qodana = { id = "org.jetbrains.qodana", version.ref = "qodana" }