Merge pull request #368 from domaframework/feature/annotation-option-parameter-validation

Enhance annotation option parameter validation for embedded properties

Author: xterao

README.md

@@ -42,6 +42,8 @@ The plugin also provides quick fixes for DAO methods where the required SQL file
   ![returnTypeInspection.png](images/returnTypeInspection.png)
 - Checks that parameters of DAO method matches the expected type based on its annotation.
   ![paramTypeInspection.png](images/paramTypeInspection.png)
+- Checks the validity of `include` and `exclude` options in `@Update`, `@BatchUpdate`, `@Insert`, `@BatchInsert`,`@MultiInsert`  and `@Returning`annotations:
+  ![inspectionAnnotationOptions.png](images/inspectionAnnotationOptions.png)
 - Checks for undefined bind variable names.
 - Checks the class name and package name for static property calls.
   ![inspectionPackageName.png](images/inspectionPackageName.png)

images/inspectionAnnotationOptions.png

@@ -67,6 +67,7 @@ enum class DomaClassName(
     SELECT_TYPE("org.seasar.doma.SelectType"),
 
     ENTITY("org.seasar.doma.Entity"),
+    EMBEDDABLE("org.seasar.doma.Embeddable"),
     DATATYPE("org.seasar.doma.DataType"),
     ;
 

src/main/kotlin/org/domaframework/doma/intellij/common/util/DomaClassName.kt

@@ -77,6 +77,14 @@ object TypeUtil {
         return clazz?.isDomain() == true
     }
 
+    fun isEmbeddable(
+        type: PsiType?,
+        project: Project,
+    ): Boolean {
+        val clazz = type?.canonicalText?.let { project.getJavaClazz(it) }
+        return clazz?.getClassAnnotation(DomaClassName.EMBEDDABLE.className) != null
+    }
+
     /**
      * Checks if the given type is a data type.
      */

src/main/kotlin/org/domaframework/doma/intellij/common/util/TypeUtil.kt

@@ -0,0 +1,56 @@
+/*
+ * 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.common.validation.result
+
+import com.intellij.codeInspection.ProblemsHolder
+import com.intellij.openapi.util.TextRange
+import com.intellij.psi.PsiElement
+import org.domaframework.doma.intellij.bundle.MessageBundle
+import org.domaframework.doma.intellij.common.psi.PsiParentClass
+
+/**
+ * Validation result for annotation option parameter errors with Embeddable types.
+ * This is used when an include/exclude option references an Embeddable field without specifying its properties.
+ */
+class ValidationAnnotationOptionEmbeddableResult(
+    override val identify: PsiElement?,
+    override val shortName: String = "",
+    private val embeddableFieldName: String,
+    private val optionName: String,
+    private val embeddableClassName: String,
+    private val availableProperties: String,
+) : ValidationResult(identify, null, shortName) {
+    override fun setHighlight(
+        highlightRange: TextRange,
+        identify: PsiElement,
+        holder: ProblemsHolder,
+        parent: PsiParentClass?,
+    ) {
+        val project = identify.project
+        holder.registerProblem(
+            identify,
+            MessageBundle.message(
+                "inspection.invalid.dao.annotation.option.embeddable",
+                embeddableFieldName,
+                optionName,
+                embeddableClassName,
+                availableProperties,
+            ),
+            problemHighlightType(project, shortName),
+            highlightRange,
+        )
+    }
+}

src/main/kotlin/org/domaframework/doma/intellij/common/validation/result/ValidationAnnotationOptionEmbeddableResult.kt

@@ -0,0 +1,56 @@
+/*
+ * 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.common.validation.result
+
+import com.intellij.codeInspection.ProblemsHolder
+import com.intellij.openapi.util.TextRange
+import com.intellij.psi.PsiElement
+import org.domaframework.doma.intellij.bundle.MessageBundle
+import org.domaframework.doma.intellij.common.psi.PsiParentClass
+
+/**
+ * Validation result for annotation option parameter errors.
+ * This is used when an include/exclude option references a non-existent field.
+ */
+class ValidationAnnotationOptionParameterResult(
+    override val identify: PsiElement?,
+    override val shortName: String = "",
+    private val invalidFieldName: String,
+    private val optionName: String,
+    private val entityName: String,
+    private val availableFields: String,
+) : ValidationResult(identify, null, shortName) {
+    override fun setHighlight(
+        highlightRange: TextRange,
+        identify: PsiElement,
+        holder: ProblemsHolder,
+        parent: PsiParentClass?,
+    ) {
+        val project = identify.project
+        holder.registerProblem(
+            identify,
+            MessageBundle.message(
+                "inspection.invalid.dao.annotation.option.field",
+                invalidFieldName,
+                optionName,
+                entityName,
+                availableFields,
+            ),
+            problemHighlightType(project, shortName),
+            highlightRange,
+        )
+    }
+}

src/main/kotlin/org/domaframework/doma/intellij/common/validation/result/ValidationAnnotationOptionParameterResult.kt

@@ -50,6 +50,8 @@ fun PsiClass.isEntity(): Boolean = this.getClassAnnotation(DomaClassName.ENTITY.
 
 fun PsiClass.isDomain(): Boolean = this.getClassAnnotation(DomaClassName.DOMAIN.className) != null
 
+fun PsiClass.isEmbeddable(): Boolean = this.getClassAnnotation(DomaClassName.EMBEDDABLE.className) != null
+
 fun PsiClass.isDataType(): Boolean = this.getClassAnnotation(DomaClassName.DATATYPE.className) != null && this.isRecord
 
 fun PsiClassType.getSuperType(superClassName: String): PsiClassType? {

src/main/kotlin/org/domaframework/doma/intellij/extension/psi/PsiClassExtension.kt

@@ -0,0 +1,39 @@
+/*
+ * 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.inspection.dao.inspector
+
+import com.intellij.codeHighlighting.HighlightDisplayLevel
+import com.intellij.codeInspection.AbstractBaseJavaLocalInspectionTool
+import com.intellij.codeInspection.ProblemsHolder
+import com.intellij.psi.PsiElementVisitor
+import org.domaframework.doma.intellij.inspection.dao.visitor.DaoAnnotationOptionParameterInspectionVisitor
+
+class DaoAnnotationOptionParameterInspection : AbstractBaseJavaLocalInspectionTool() {
+    override fun getDisplayName(): String = "Check annotation option parameters of DAO method"
+
+    override fun getShortName(): String = "org.domaframework.doma.intellij.annotation.option"
+
+    override fun getGroupDisplayName(): String = "DomaTools"
+
+    override fun isEnabledByDefault(): Boolean = true
+
+    override fun getDefaultLevel(): HighlightDisplayLevel = HighlightDisplayLevel.ERROR
+
+    override fun buildVisitor(
+        holder: ProblemsHolder,
+        isOnTheFly: Boolean,
+    ): PsiElementVisitor = DaoAnnotationOptionParameterInspectionVisitor(holder, this.shortName)
+}

src/main/kotlin/org/domaframework/doma/intellij/inspection/dao/inspector/DaoAnnotationOptionParameterInspection.kt

@@ -40,8 +40,9 @@ import org.domaframework.doma.intellij.extension.psi.isDomain
  * @property project The IntelliJ project instance.
  */
 abstract class TypeCheckerProcessor(
-    psiDaoMethod: PsiDaoMethod,
+    private val psiDaoMethod: PsiDaoMethod,
 ) {
+    protected val returningFqn = DomaClassName.RETURNING.className
     protected val method = psiDaoMethod.psiMethod
     protected val project = method.project
 
@@ -52,6 +53,13 @@ abstract class TypeCheckerProcessor(
             (param.type as? PsiClassType)?.getSuperType(typeName) != null
         }
 
+    protected fun hasReturingOption(): Boolean {
+        val methodAnnotation: PsiAnnotation =
+            getAnnotation(psiDaoMethod.daoType.fqdn) ?: return false
+        val returningOption: PsiAnnotation? = getDaoAnnotationOption(methodAnnotation, "returning")
+        return returningOption?.nameReferenceElement?.qualifiedName == returningFqn
+    }
+
     protected fun getDaoAnnotationOption(
         psiAnnotation: PsiAnnotation,
         findOptionName: String,

src/main/kotlin/org/domaframework/doma/intellij/inspection/dao/processor/TypeCheckerProcessor.kt

@@ -0,0 +1,164 @@
+/*
+ * 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.inspection.dao.processor.option
+
+import com.intellij.codeInspection.ProblemsHolder
+import com.intellij.openapi.project.Project
+import com.intellij.psi.PsiAnnotation
+import com.intellij.psi.PsiClass
+import com.intellij.psi.PsiClassType
+import com.intellij.psi.PsiField
+import com.intellij.psi.PsiLiteralExpression
+import org.domaframework.doma.intellij.common.psi.PsiDaoMethod
+import org.domaframework.doma.intellij.common.util.TypeUtil
+import org.domaframework.doma.intellij.common.validation.result.ValidationAnnotationOptionEmbeddableResult
+import org.domaframework.doma.intellij.common.validation.result.ValidationAnnotationOptionParameterResult
+import org.domaframework.doma.intellij.extension.getJavaClazz
+import org.domaframework.doma.intellij.extension.psi.DomaAnnotationType
+import org.domaframework.doma.intellij.extension.psi.isEmbeddable
+import org.domaframework.doma.intellij.extension.psi.isEntity
+import org.domaframework.doma.intellij.inspection.dao.processor.TypeCheckerProcessor
+
+/**
+ * Processor for checking annotation option parameters in DAO methods.
+ * This class validates the include and exclude options in @Update and @BatchUpdate annotations.
+ */
+class DaoAnnotationOptionParameterCheckProcessor(
+    private val psiDaoMethod: PsiDaoMethod,
+    private val shortName: String,
+) : TypeCheckerProcessor(psiDaoMethod) {
+    fun checkAnnotationOptions(holder: ProblemsHolder) {
+        val annotation = getAnnotation(psiDaoMethod.daoType.fqdn) ?: return
+
+        // Check if sqlFile option is true - if so, include/exclude are not referenced
+        if (psiDaoMethod.isUseSqlFileMethod() || psiDaoMethod.useSqlAnnotation()) {
+            return
+        }
+
+        // Get the entity parameter
+        val methodParams = method.parameterList.parameters
+        val entityParam = methodParams.firstOrNull() ?: return
+        var entityType = entityParam.type
+
+        // For batch operations, extract the element type from Iterable
+        if (psiDaoMethod.daoType.isBatchAnnotation() || psiDaoMethod.daoType == DomaAnnotationType.MultiInsert) {
+            val paramClassType = entityType as? PsiClassType
+            val iterableParam = paramClassType?.parameters?.firstOrNull()
+            if (iterableParam != null) {
+                entityType = iterableParam
+            }
+        }
+
+        val entityClass = project.getJavaClazz(entityType.canonicalText) ?: return
+        if (!entityClass.isEntity()) {
+            return
+        }
+
+        checkAnnotationOptions(annotation, entityClass, holder)
+
+        val returningOption = getDaoAnnotationOption(annotation, "returning") ?: return
+        if (hasReturingOption()) {
+            checkAnnotationOptions(returningOption, entityClass, holder)
+        }
+    }
+
+    private fun checkAnnotationOptions(
+        annotation: PsiAnnotation,
+        entityClass: PsiClass,
+        holder: ProblemsHolder,
+    ) {
+        checkArrayOption(annotation, "include", entityClass, holder)
+        checkArrayOption(annotation, "exclude", entityClass, holder)
+    }
+
+    private fun checkArrayOption(
+        annotation: PsiAnnotation,
+        optionName: String,
+        entityClass: PsiClass,
+        holder: ProblemsHolder,
+    ) {
+        val arrayValues =
+            annotation.parameterList.attributes
+                .find { it.name == optionName }
+                ?.value
+                ?.children
+                ?.filter { it is PsiLiteralExpression } ?: return
+        if (arrayValues.isEmpty()) return
+
+        val project = method.project
+        arrayValues.map { fields ->
+            val valueFields = fields.text.replace("\"", "").split(".")
+            var searchParamClass: PsiClass? = entityClass
+            var preSearchParamClass: PsiClass? = entityClass
+            var hasError = false
+            valueFields.map { field ->
+                searchParamClass
+                    ?.fields
+                    ?.find { property -> isOptionTargetProperty(property, field, project) }
+                    ?.let { f ->
+                        preSearchParamClass = searchParamClass
+                        searchParamClass = project.getJavaClazz(f.type.canonicalText) ?: return@map
+                    }
+                    ?: run {
+                        ValidationAnnotationOptionParameterResult(
+                            fields,
+                            shortName,
+                            field,
+                            optionName,
+                            searchParamClass?.name ?: "Unknown",
+                            getTargetOptionProperties(preSearchParamClass),
+                        ).highlightElement(holder)
+                        hasError = true
+                        return@map
+                    }
+            }
+            // Error if the last field is Embeddable
+            if (!hasError && searchParamClass?.isEmbeddable() == true) {
+                ValidationAnnotationOptionEmbeddableResult(
+                    fields,
+                    shortName,
+                    valueFields.lastOrNull() ?: "Unknown",
+                    optionName,
+                    searchParamClass.name ?: "Unknown",
+                    getEmbeddableProperties(searchParamClass),
+                ).highlightElement(holder)
+            }
+        }
+    }
+
+    private fun getTargetOptionProperties(paramClass: PsiClass?) =
+        paramClass?.fields?.filter { isOptionTargetProperty(it, it.name, project) }?.joinToString(", ") { it.name.substringAfter(":") }
+            ?: "No fields found"
+
+    private fun getEmbeddableProperties(embeddableClass: PsiClass?) =
+        embeddableClass
+            ?.fields
+            ?.filter { !TypeUtil.isEntity(it.type, project) && !TypeUtil.isEmbeddable(it.type, project) }
+            ?.joinToString(", ") { it.name }
+            ?: "No properties found"
+
+    private fun isOptionTargetProperty(
+        field: PsiField,
+        optionPropertyName: String,
+        project: Project,
+    ): Boolean =
+        (
+            field.name == optionPropertyName && (
+                !TypeUtil.isEntity(field.type, project) ||
+                    TypeUtil.isEmbeddable(field.type, project)
+            )
+        )
+}