Merge pull request #8 from j-plugins/claude/serene-knuth-A9CBJ

feat: add support for listing message-bus topics contributed by plugins

Author: xepozz

doc-processor/build.gradle.kts

@@ -3,7 +3,7 @@ plugins {
 }
 
 dependencies {
-    implementation("com.google.devtools.ksp:symbol-processing-api:2.1.20-1.0.32")
+    implementation("com.google.devtools.ksp:symbol-processing-api:2.3.8")
 }
 
 kotlin {

docs/MCP_TOOLS.md

@@ -6,10 +6,10 @@ include(":doc-processor")
 
 pluginManagement {
     plugins {
-        id("org.jetbrains.kotlin.jvm") version "2.1.20"
-        id("org.jetbrains.kotlin.plugin.serialization") version "2.1.20"
+        id("org.jetbrains.kotlin.jvm") version "2.3.21"
+        id("org.jetbrains.kotlin.plugin.serialization") version "2.3.21"
         id("org.jetbrains.changelog") version "2.5.0"
-        id("com.google.devtools.ksp") version "2.1.20-1.0.32"
+        id("com.google.devtools.ksp") version "2.3.8"
         id("org.jetbrains.kotlinx.kover") version "0.9.8"
     }
 }

settings.gradle.kts

@@ -0,0 +1,107 @@
+package com.github.xepozz.ide.introspector.core
+
+import com.github.xepozz.ide.introspector.model.ListenerInfo
+import com.intellij.ide.plugins.IdeaPluginDescriptor
+import com.intellij.ide.plugins.PluginManagerCore
+import com.intellij.openapi.diagnostic.thisLogger
+
+/**
+ * Reads `<applicationListeners>` and `<projectListeners>` declarations off the live
+ * [com.intellij.ide.plugins.IdeaPluginDescriptorImpl.appContainerDescriptor] /
+ * `projectContainerDescriptor`. Uses reflection because both [com.intellij.util.messages.ListenerDescriptor]
+ * and the container class are `@ApiStatus.Internal`.
+ *
+ * Runtime `messageBus.connect().subscribe(...)` subscribers are out of scope — they're attached
+ * imperatively, not declaratively, and the platform doesn't expose a deterministic enumeration.
+ */
+object ListenerInspector {
+
+    fun listAll(): List<ListenerInfo> {
+        val out = mutableListOf<ListenerInfo>()
+        for (descriptor in PluginManagerCore.plugins) {
+            collectFor(descriptor, out)
+        }
+        return out
+    }
+
+    fun listForPlugin(descriptor: IdeaPluginDescriptor): List<ListenerInfo> {
+        val out = mutableListOf<ListenerInfo>()
+        collectFor(descriptor, out)
+        return out
+    }
+
+    private fun collectFor(descriptor: IdeaPluginDescriptor, out: MutableList<ListenerInfo>) {
+        val pluginId = descriptor.pluginId.idString
+        val pluginName = descriptor.name
+        for ((areaTag, getter) in AREA_GETTERS) {
+            val container = readContainer(descriptor, getter) ?: continue
+            val listeners = readListenerList(container)
+            for (ld in listeners) {
+                out += try {
+                    toListenerInfo(ld, areaTag, pluginId, pluginName)
+                } catch (t: Throwable) {
+                    thisLogger().debug("Failed to read ListenerDescriptor for $pluginId/$areaTag", t)
+                    null
+                } ?: continue
+            }
+        }
+    }
+
+    internal fun toListenerInfo(
+        ld: Any,
+        areaTag: String,
+        pluginId: String,
+        pluginName: String?,
+    ): ListenerInfo? {
+        val listenerClass = readField(ld, "listenerClassName")?.toString() ?: return null
+        val topicClass = readField(ld, "topicClassName")?.toString() ?: return null
+        val activeInTest = (readField(ld, "activeInTestMode") as? Boolean) ?: true
+        val activeInHeadless = (readField(ld, "activeInHeadlessMode") as? Boolean) ?: true
+        val os = readField(ld, "os")?.let { runCatching { (it as Enum<*>).name }.getOrNull() }
+        return ListenerInfo(
+            topicClass = topicClass,
+            listenerClass = listenerClass,
+            area = areaTag,
+            activeInTestMode = activeInTest,
+            activeInHeadlessMode = activeInHeadless,
+            os = os,
+            providedByPluginId = pluginId,
+            providedByPluginName = pluginName,
+        )
+    }
+
+    private fun readContainer(descriptor: IdeaPluginDescriptor, getterName: String): Any? {
+        val m = descriptor.javaClass.methods.firstOrNull {
+            it.name == getterName && it.parameterCount == 0
+        } ?: return null
+        return try { m.invoke(descriptor) } catch (_: Throwable) { null }
+    }
+
+    private fun readListenerList(container: Any): List<Any> {
+        // ContainerDescriptor.listeners is a @JvmField — public field on the JVM.
+        val field = container.javaClass.fields.firstOrNull { it.name == "listeners" }
+            ?: return emptyList()
+        val raw = try { field.get(container) } catch (_: Throwable) { return emptyList() }
+        return (raw as? List<*>)?.filterNotNull().orEmpty()
+    }
+
+    private fun readField(target: Any, name: String): Any? {
+        var c: Class<*>? = target.javaClass
+        while (c != null) {
+            val f = c.declaredFields.firstOrNull { it.name == name }
+            if (f != null) {
+                return try {
+                    f.isAccessible = true
+                    f.get(target)
+                } catch (_: Throwable) { null }
+            }
+            c = c.superclass
+        }
+        return null
+    }
+
+    private val AREA_GETTERS = listOf(
+        "application" to "getAppContainerDescriptor",
+        "project" to "getProjectContainerDescriptor",
+    )
+}

src/main/kotlin/com/github/xepozz/ide/introspector/core/ListenerInspector.kt

@@ -3,11 +3,16 @@ package com.github.xepozz.ide.introspector.core
 import com.github.xepozz.ide.introspector.core.internal.TtlCache
 import com.github.xepozz.ide.introspector.model.ExtensionInfo
 import com.github.xepozz.ide.introspector.model.ExtensionPointInfo
+import com.github.xepozz.ide.introspector.model.ListenerInfo
 import com.github.xepozz.ide.introspector.model.PluginDependencyInfo
 import com.github.xepozz.ide.introspector.model.PluginInfo
+import com.github.xepozz.ide.introspector.model.ServiceInfo
+import com.github.xepozz.ide.introspector.model.TopicInfo
 import com.intellij.ide.plugins.PluginManagerCore
 import com.intellij.openapi.components.Service
 import com.intellij.openapi.components.service
+import com.intellij.openapi.extensions.PluginId
+import java.util.concurrent.ConcurrentHashMap
 
 /**
  * Application-level cache of plugin + EP + extension data. Both the MCP arch.* tools
@@ -24,19 +29,67 @@ class PluginInventory {
         val plugins: List<PluginInfo>,
         val extensionPoints: List<ExtensionPointInfo>,
         val extensionsByEp: Map<String, List<ExtensionInfo>>,
+        val servicesByPluginId: Map<String, List<ServiceInfo>>,
+        val listenersByPluginId: Map<String, List<ListenerInfo>>,
     )
 
     private val cache = TtlCache<Snapshot>(ttlMs = CACHE_TTL_MS) { collect() }
+    // Light-service walk is non-deterministic (depends on what's been touched in the IDE).
+    // Kept on a shorter TTL and separate from the deterministic snapshot.
+    private val lightServiceCache = TtlCache<List<ServiceInfo>>(ttlMs = LIGHT_SERVICE_TTL_MS) {
+        val xmlImpls = snapshot().servicesByPluginId.values.asSequence()
+            .flatten().map { it.implementationClass }.toSet()
+        ServiceInspector.listLightInstantiated(xmlImpls)
+    }
+    // Topics scanning walks every plugin's classpath and is expensive — kept OUT of the
+    // main snapshot. Computed on demand per plugin and cached forever (until refresh()),
+    // since a plugin's declared topics don't change while the IDE is running.
+    private val topicsByPluginCache = ConcurrentHashMap<String, List<TopicInfo>>()
 
     fun snapshot(forceRefresh: Boolean = false): Snapshot = cache.get(forceRefresh)
 
-    fun refresh() { cache.invalidate(); cache.get() }
+    fun refresh() {
+        cache.invalidate()
+        lightServiceCache.invalidate()
+        topicsByPluginCache.clear()
+        cache.get()
+    }
 
     fun plugins(): List<PluginInfo> = snapshot().plugins
     fun extensionPoints(): List<ExtensionPointInfo> = snapshot().extensionPoints
     fun extensionsByEp(): Map<String, List<ExtensionInfo>> = snapshot().extensionsByEp
     fun extensionsForEp(name: String): List<ExtensionInfo> = extensionsByEp()[name] ?: emptyList()
 
+    fun services(): List<ServiceInfo> = snapshot().servicesByPluginId.values.flatten()
+    fun listeners(): List<ListenerInfo> = snapshot().listenersByPluginId.values.flatten()
+    fun servicesByPlugin(pluginId: String): List<ServiceInfo> =
+        snapshot().servicesByPluginId[pluginId] ?: emptyList()
+    fun listenersByPlugin(pluginId: String): List<ListenerInfo> =
+        snapshot().listenersByPluginId[pluginId] ?: emptyList()
+    /**
+     * Returns topics declared by [pluginId], scanning the plugin's classpath on first
+     * request and caching the result. Returns empty if the plugin id is unknown or its
+     * descriptor exposes no classloader.
+     */
+    fun topicsByPlugin(pluginId: String): List<TopicInfo> = topicsByPluginCache.computeIfAbsent(pluginId) {
+        val descriptor = PluginManagerCore.getPlugin(PluginId.getId(pluginId)) ?: return@computeIfAbsent emptyList()
+        TopicInspector.listForPlugin(descriptor)
+    }
+
+    /**
+     * Flattens topics across *already-scanned* plugins. Does NOT trigger scans for
+     * unseen plugins — call [topicsByPlugin] (or [scanTopicsForPlugins]) first.
+     */
+    fun topics(): List<TopicInfo> = topicsByPluginCache.values.flatten()
+
+    /** Forces topic scanning for the given plugin ids (each cached on first call). */
+    fun scanTopicsForPlugins(pluginIds: Collection<String>) {
+        for (id in pluginIds) topicsByPlugin(id)
+    }
+
+    /** Light services already created in this IDE session. Non-deterministic, separate TTL. */
+    fun lightInstantiatedServices(): List<ServiceInfo> = lightServiceCache.get()
+
     private fun collect(): Snapshot {
         val now = System.currentTimeMillis()
         val eps = ExtensionPointInspector.listExtensionPoints("both")
@@ -51,6 +104,15 @@ class PluginInventory {
         // Count EPs and extensions per plugin for the PluginInfo summary fields.
         val declaredCountByPluginId = eps.groupingBy { it.declaredByPluginId }.eachCount()
 
+        val servicesByPluginId = mutableMapOf<String, MutableList<ServiceInfo>>()
+        for (s in ServiceInspector.listAll()) {
+            servicesByPluginId.getOrPut(s.providedByPluginId) { mutableListOf() }.add(s)
+        }
+        val listenersByPluginId = mutableMapOf<String, MutableList<ListenerInfo>>()
+        for (l in ListenerInspector.listAll()) {
+            listenersByPluginId.getOrPut(l.providedByPluginId) { mutableListOf() }.add(l)
+        }
+
         @Suppress("UnstableApiUsage")
         val plugins = PluginManagerCore.plugins.map { descriptor ->
             val depList = descriptor.dependencies
@@ -60,22 +122,33 @@ class PluginInventory {
                         optional = dep.isOptional,
                     )
                 }
+            val id = descriptor.pluginId.idString
             PluginInfo(
-                id = descriptor.pluginId.idString,
-                name = descriptor.name ?: descriptor.pluginId.idString,
+                id = id,
+                name = descriptor.name ?: id,
                 version = descriptor.version,
                 vendor = descriptor.vendor,
                 isBundled = descriptor.isBundled,
                 isEnabled = readIsEnabled(descriptor),
                 sinceBuild = descriptor.sinceBuild,
                 untilBuild = descriptor.untilBuild,
                 dependencies = depList,
-                declaredExtensionPointsCount = declaredCountByPluginId[descriptor.pluginId.idString] ?: 0,
+                declaredExtensionPointsCount = declaredCountByPluginId[id] ?: 0,
                 registeredExtensionsCount = 0,             // computed lazily when needed
+                servicesCount = servicesByPluginId[id]?.size ?: 0,
+                listenersCount = listenersByPluginId[id]?.size ?: 0,
+                topicsCount = topicsByPluginCache[id]?.size ?: 0,
             )
         }.sortedBy { it.name.lowercase() }
 
-        return Snapshot(now, plugins, eps, extensionsByEp)
+        return Snapshot(
+            takenAtMs = now,
+            plugins = plugins,
+            extensionPoints = eps,
+            extensionsByEp = extensionsByEp,
+            servicesByPluginId = servicesByPluginId.mapValues { it.value.toList() },
+            listenersByPluginId = listenersByPluginId.mapValues { it.value.toList() },
+        )
     }
 
     /** Lazily computes the extensions for a single EP and updates the cache map. */
@@ -103,6 +176,7 @@ class PluginInventory {
 
     companion object {
         const val CACHE_TTL_MS = 30_000L
+        const val LIGHT_SERVICE_TTL_MS = 10_000L
         fun getInstance(): PluginInventory = service()
 
         /** [IdeaPluginDescriptor.isEnabled] is deprecated; check via [PluginManagerCore.isDisabled]. */

src/main/kotlin/com/github/xepozz/ide/introspector/core/PluginInventory.kt

@@ -1,15 +1,11 @@
 package com.github.xepozz.ide.introspector.core
 
-import com.github.xepozz.ide.introspector.util.MAX_IMAGE_BYTES
-import com.github.xepozz.ide.introspector.util.scaleImage
 import com.intellij.openapi.wm.WindowManager
 import java.awt.Component
 import java.awt.Graphics2D
 import java.awt.Rectangle
 import java.awt.Robot
 import java.awt.image.BufferedImage
-import java.io.ByteArrayOutputStream
-import javax.imageio.ImageIO
 
 /**
  * Renders a [Component] off-screen via Component.paint(Graphics) — pure rendering, no
@@ -41,34 +37,4 @@ object ScreenshotCapture {
         val frame = WindowManager.getInstance().findVisibleFrame() ?: return null
         return captureComponent(frame)
     }
-
-    /** Auto-downscales [image] until its PNG size is within [MAX_IMAGE_BYTES]. */
-    fun fitWithinBudget(image: BufferedImage): Pair<BufferedImage, String?> =
-        fitWithinBudget(image, MAX_IMAGE_BYTES, maxAttempts = 4)
-
-    /**
-     * Test-visible overload: same algorithm as [fitWithinBudget] but parameterised so tests
-     * can drive it with smaller budgets / attempt caps instead of producing many-MB images.
-     */
-    internal fun fitWithinBudget(
-        image: BufferedImage,
-        budgetBytes: Int,
-        maxAttempts: Int,
-    ): Pair<BufferedImage, String?> {
-        var current = image
-        var warning: String? = null
-        var attempts = 0
-        while (encodedSize(current) > budgetBytes && attempts < maxAttempts) {
-            current = scaleImage(current, 0.5)
-            attempts++
-            warning = "Image was downscaled to fit MCP response size budget (${attempts} halving passes)."
-        }
-        return current to warning
-    }
-
-    internal fun encodedSize(image: BufferedImage): Int {
-        val baos = ByteArrayOutputStream()
-        ImageIO.write(image, "png", baos)
-        return baos.size()
-    }
 }