Add ForItemElementDocumentationProvider for enhanced documentation support

xterao · xterao · commit b1cf7df8de5f · 2025-04-28T17:35:12.000+09:00
diff --git a/src/main/kotlin/org/domaframework/doma/intellij/document/ForItemElementDocumentationProvider.kt b/src/main/kotlin/org/domaframework/doma/intellij/document/ForItemElementDocumentationProvider.kt
@@ -0,0 +1,214 @@
+/*
+ * Copyright Doma Tools Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.domaframework.doma.intellij.document
+
+import com.intellij.lang.documentation.AbstractDocumentationProvider
+import com.intellij.psi.PsiClassType
+import com.intellij.psi.PsiElement
+import org.domaframework.doma.intellij.common.dao.findDaoMethod
+import org.domaframework.doma.intellij.common.psi.PsiParentClass
+import org.domaframework.doma.intellij.common.sql.PsiClassTypeUtil
+import org.domaframework.doma.intellij.common.sql.foritem.ForItem
+import org.domaframework.doma.intellij.common.sql.validator.SqlElForItemFieldAccessorChildElementValidator
+import org.domaframework.doma.intellij.common.sql.validator.result.ValidationCompleteResult
+import org.domaframework.doma.intellij.common.sql.validator.result.ValidationResult
+import org.domaframework.doma.intellij.extension.psi.getForItem
+import org.domaframework.doma.intellij.extension.psi.getForItemDeclaration
+import org.domaframework.doma.intellij.inspection.ForDirectiveInspection
+import org.domaframework.doma.intellij.psi.SqlElForDirective
+import org.domaframework.doma.intellij.psi.SqlElIdExpr
+import org.domaframework.doma.intellij.psi.SqlTypes
+import org.toml.lang.psi.ext.elementType
+import java.util.LinkedList
+
+class ForItemElementDocumentationProvider : AbstractDocumentationProvider() {
+    override fun generateDoc(
+        element: PsiElement?,
+        originalElement: PsiElement?,
+    ): String? {
+        val result: MutableList<String?> = LinkedList<String?>()
+        if (originalElement !is SqlElIdExpr && originalElement?.elementType != SqlTypes.EL_IDENTIFIER) {
+            return super.generateDoc(
+                element,
+                originalElement,
+            )
+        }
+
+        val file = originalElement.containingFile
+        val daoMethod = findDaoMethod(file) ?: return ""
+        val forDirectiveInspection = ForDirectiveInspection(daoMethod, "")
+
+        val currentForItem = ForItem(originalElement)
+        val forDirectiveExpr = currentForItem.getParentForDirectiveExpr()
+        if (forDirectiveExpr != null) {
+            if (forDirectiveExpr.getForItem()?.textOffset != originalElement.textOffset) {
+                val declarationClassType =
+                    forDirectiveInspection.validateFieldAccessByForItem(
+                        listOf(originalElement),
+                        skipSelf = false,
+                    )
+                if (declarationClassType != null) {
+                    generateDocumentInForDirective(
+                        declarationClassType,
+                        forDirectiveExpr,
+                        originalElement,
+                        result,
+                    )
+                }
+            } else {
+                val declarationSide = forDirectiveExpr.getForItemDeclaration() ?: return ""
+                val children = declarationSide.getDeclarationChildren()
+                generateDocumentInForItem(
+                    forDirectiveInspection,
+                    originalElement,
+                    children,
+                    result,
+                )
+            }
+        } else {
+            generateDocumentInBindVariable(forDirectiveInspection, originalElement, result)
+        }
+        return result.joinToString("\n")
+    }
+
+    private fun generateDocumentInForItem(
+        forDirectiveInspection: ForDirectiveInspection,
+        originalElement: PsiElement,
+        declarationChildren: List<SqlElIdExpr>,
+        result: MutableList<String?>,
+    ) {
+        val declarationClassType =
+            forDirectiveInspection.validateFieldAccessByForItem(listOf(originalElement), false)
+        if (declarationClassType is ValidationCompleteResult) {
+            val parentClass = declarationClassType.parentClass
+            val forItemValidator =
+                SqlElForItemFieldAccessorChildElementValidator(
+                    declarationChildren,
+                    parentClass,
+                )
+            val declarationClassTypeResult = forItemValidator.validateChildren()
+            if (declarationClassTypeResult is ValidationCompleteResult) {
+                var resultParent = declarationClassTypeResult.parentClass
+                var classType: PsiClassType? = resultParent.type as? PsiClassType
+                if (classType != null &&
+                    PsiClassTypeUtil.isIterableType(classType, originalElement.project)
+                ) {
+                    classType = classType.parameters.firstOrNull() as? PsiClassType
+                }
+                if (classType != null) {
+                    resultParent = PsiParentClass(classType)
+                    result.add("${generateTypeLink(resultParent)} ${originalElement.text}")
+                }
+            }
+        }
+    }
+
+    private fun generateDocumentInBindVariable(
+        forDirectiveInspection: ForDirectiveInspection,
+        originalElement: PsiElement,
+        result: MutableList<String?>,
+    ) {
+        val declarationClassType =
+            forDirectiveInspection.validateFieldAccessByForItem(listOf(originalElement))
+        if (declarationClassType != null) {
+            val parentClass = declarationClassType.parentClass
+            result.add("${generateTypeLink(parentClass)} ${originalElement.text}")
+        }
+    }
+
+    private fun generateDocumentInForDirective(
+        declarationClassType: ValidationResult,
+        forDirectiveExpr: SqlElForDirective,
+        originalElement: PsiElement,
+        result: MutableList<String?>,
+    ) {
+        val parentClass = declarationClassType.parentClass
+        val parentType = parentClass?.type as? PsiClassType
+
+        if (forDirectiveExpr.getForItem()?.textOffset == originalElement.textOffset) {
+            generateDocumentForItemSelf(parentType, originalElement, result)
+        } else {
+            result.add("${generateTypeLink(parentClass)} ${originalElement.text}")
+        }
+    }
+
+    private fun generateDocumentForItemSelf(
+        parentType: PsiClassType?,
+        originalElement: PsiElement,
+        result: MutableList<String?>,
+    ) {
+        val targetClassType =
+            if (parentType != null &&
+                PsiClassTypeUtil.isIterableType(parentType, originalElement.project)
+            ) {
+                parentType.parameters.firstOrNull()
+            } else {
+                null
+            }
+
+        if (targetClassType != null) {
+            val forItemParentClassType = PsiParentClass(targetClassType)
+            result.add("${generateTypeLink(forItemParentClassType)} ${originalElement.text}")
+        }
+    }
+
+    override fun generateHoverDoc(
+        element: PsiElement,
+        originalElement: PsiElement?,
+    ): String? = generateDoc(element, originalElement)
+
+    override fun getQuickNavigateInfo(
+        element: PsiElement,
+        originalElement: PsiElement?,
+    ): String? {
+        val result: MutableList<String?> = LinkedList<String?>()
+        val typeDocument = generateDoc(element, originalElement)
+        result.add(typeDocument)
+        return result.joinToString("\n")
+    }
+
+    private fun generateTypeLink(parentClass: PsiParentClass?): String {
+        if (parentClass?.type != null) {
+            return generateTypeLinkFromCanonicalText(parentClass.type.canonicalText)
+        }
+        return ""
+    }
+
+    private fun generateTypeLinkFromCanonicalText(canonicalText: String): String {
+        val regex = Regex("([a-zA-Z0-9_]+\\.)*([a-zA-Z0-9_]+)")
+        val result = StringBuilder()
+        var lastIndex = 0
+
+        for (match in regex.findAll(canonicalText)) {
+            val fullMatch = match.value
+            val typeName = match.groups[2]?.value ?: fullMatch
+            val startIndex = match.range.first
+            val endIndex = match.range.last + 1
+
+            if (lastIndex < startIndex) {
+                result.append(canonicalText.substring(lastIndex, startIndex))
+            }
+            result.append("<a href=\"psi_element://$fullMatch\">$typeName</a>")
+            lastIndex = endIndex
+        }
+
+        if (lastIndex < canonicalText.length) {
+            result.append(canonicalText.substring(lastIndex))
+        }
+
+        return result.toString()
+    }
+}
diff --git a/src/main/kotlin/org/domaframework/doma/intellij/inspection/ForDirectiveInspection.kt b/src/main/kotlin/org/domaframework/doma/intellij/inspection/ForDirectiveInspection.kt
@@ -62,8 +62,11 @@ class ForDirectiveInspection(
     private val cachedForDirectiveBlocks: MutableMap<PsiElement, CachedValue<List<BlockToken>>> =
         mutableMapOf()
 
-    fun getForItem(targetElement: PsiElement): ForItem? {
-        val forBlocks = getForDirectiveBlock(targetElement)
+    fun getForItem(
+        targetElement: PsiElement,
+        skipSelf: Boolean = true,
+    ): ForItem? {
+        val forBlocks = getForDirectiveBlock(targetElement, skipSelf)
         return getForItem(targetElement, forBlocks)
     }
 
@@ -83,11 +86,14 @@ class ForDirectiveInspection(
      * Analyze the field access of the for item definition and finally get the declared type
      * @return [ValidationResult] is used to display the analysis results.
      */
-    fun validateFieldAccessByForItem(blockElements: List<PsiElement>): ValidationResult? {
+    fun validateFieldAccessByForItem(
+        blockElements: List<PsiElement>,
+        skipSelf: Boolean = true,
+    ): ValidationResult? {
         val targetElement: PsiElement = blockElements.firstOrNull() ?: return null
         val topElm = blockElements.first()
 
-        val forDirectives = getForDirectiveBlock(targetElement)
+        val forDirectives = getForDirectiveBlock(targetElement, skipSelf)
         val forItem = getForItem(targetElement, forDirectives) ?: return createErrorResult(targetElement)
         val domaAnnotationType = daoMethod.getDomaAnnotationType()
 
@@ -114,8 +120,8 @@ class ForDirectiveInspection(
         topElm: PsiElement,
     ): PsiClassType? {
         var nestClassType: PsiClassType? = if (isBatchAnnotation) initialType.parameters.firstOrNull() as? PsiClassType else initialType
-        var listIndex = 1
 
+        // Follow the For directive and get the definition type of the current directive from the top definition type.
         for ((i, targetForDirective) in forDirectives.withIndex()) {
             if (nestClassType == null) break
             val targetDirectiveParent =
@@ -128,26 +134,28 @@ class ForDirectiveInspection(
                     topElm,
                     SqlElForDirective::class.java,
                 )
+
+            // Skip if the For directive in the search target is the same directory as the self.
             if (targetDirectiveParent == targetElementParent) continue
 
             val currentForItem = ForItem(targetForDirective.item)
             val currentDeclaration = currentForItem.getParentForDirectiveExpr()?.getForItemDeclaration() ?: continue
-
             val declarationType = processDeclarationElement(currentDeclaration, nestClassType, i)
             if (declarationType != null) {
                 if (!PsiClassTypeUtil.isIterableType(declarationType, topElm.project)) {
                     return null
                 }
                 nestClassType = declarationType.parameters.firstOrNull() as? PsiClassType
-                listIndex = 1
             } else {
-                nestClassType = processListType(nestClassType, listIndex, topElm)
-                listIndex++
+                nestClassType = processListType(nestClassType, topElm)
             }
         }
         return nestClassType
     }
 
+    /**
+     * Check the For directive definition element of the search target and get the declaration type
+     */
     private fun processDeclarationElement(
         currentDeclaration: ForDeclarationItem,
         nestClassType: PsiClassType,
@@ -162,23 +170,25 @@ class ForDirectiveInspection(
 
         val declarationChildren = currentDeclaration.getDeclarationChildren()
         if (declarationChildren.size > 1) {
+            // Gets the type of reference property if it is defined with field access
             val validator = SqlElForItemFieldAccessorChildElementValidator(declarationChildren, PsiParentClass(nestClassType), shortName)
             return validator.validateChildren()?.parentClass?.type as? PsiClassType
         }
         return null
     }
 
+    /**
+     * Dig down the List definition type for the number of nesting levels
+     * from the top For directive definition type to obtain the type that applies to the current directive.
+     */
     private fun processListType(
         nestClassType: PsiClassType,
-        listIndex: Int,
         topElm: PsiElement,
     ): PsiClassType? {
         var currentType: PsiClassType? = nestClassType
-        repeat(listIndex) {
-            currentType?.let { type ->
-                if (PsiClassTypeUtil.isIterableType(type, topElm.project)) {
-                    currentType = type.parameters.firstOrNull() as? PsiClassType
-                }
+        currentType?.let { type ->
+            if (PsiClassTypeUtil.isIterableType(type, topElm.project)) {
+                currentType = type.parameters.firstOrNull() as? PsiClassType
             }
         }
         return currentType
@@ -191,7 +201,10 @@ class ForDirectiveInspection(
      * to the target element (`targetElement`)
      * and obtain the `for` block information to which the `targetElement` belongs.
      */
-    private fun getForDirectiveBlock(targetElement: PsiElement): List<BlockToken> {
+    private fun getForDirectiveBlock(
+        targetElement: PsiElement,
+        skipSelf: Boolean = true,
+    ): List<BlockToken> {
         val cachedValue =
             cachedForDirectiveBlocks.getOrPut(targetElement) {
                 CachedValuesManager.getManager(targetElement.project).createCachedValue {
@@ -222,7 +235,12 @@ class ForDirectiveInspection(
                                 }
                             }
                     val stack = mutableListOf<BlockToken>()
-                    val filterPosition = directiveBlocks.filter { it.position < targetElement.textOffset }
+                    val filterPosition =
+                        if (skipSelf) {
+                            directiveBlocks.filter { it.position < targetElement.textOffset }
+                        } else {
+                            directiveBlocks.filter { it.position <= targetElement.textOffset }
+                        }
                     filterPosition.forEach { block ->
                         when (block.type) {
                             BlockType.FOR, BlockType.IF -> stack.add(block)
diff --git a/src/main/resources/META-INF/plugin.xml b/src/main/resources/META-INF/plugin.xml
@@ -24,14 +24,18 @@
         instance="org.domaframework.doma.intellij.setting.DomaToolsConfigurable"
         displayName="Doma Tools" />
 
+    <!-- Reference -->
     <psi.referenceContributor
       implementation="org.domaframework.doma.intellij.reference.SqlReferenceContributor"
       language="DomaSql"
     />
-
     <lang.elementManipulator forClass="org.domaframework.doma.intellij.psi.SqlCustomElExpr"
       implementationClass="org.domaframework.doma.intellij.reference.SqlElExprManipulator" />
 
+    <!-- Document -->
+    <lang.documentationProvider language="DomaSql"
+      implementationClass="org.domaframework.doma.intellij.document.ForItemElementDocumentationProvider" />
+
     <!-- Gutter -->
     <codeInsight.lineMarkerProvider language="JAVA"
       implementationClass="org.domaframework.doma.intellij.gutter.dao.DaoMethodProvider"/>
