Introduce extracted parameter properties in Statement interface, refactor RepositoryProcessor and TableProcessor, and replace QueryValidator with updated SqlValidator.

smyrgeorge · smyrgeorge · commit 5e21e1d96d5a · 2025-10-01T10:49:16.000+02:00
diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml
@@ -32,6 +32,8 @@ jsqlparser = "5.3"
 # https://mvnrepository.com/artifact/org.apache.calcite/calcite-core/1.40.0
 # https://github.com/apache/calcite
 calcite = "1.40.0"
+# https://github.com/smyrgeorge/log4k
+log4k = "1.1.1"
 
 [libraries]
 gradle-kotlin-plugin = { module = "org.jetbrains.kotlin:kotlin-gradle-plugin", version.ref = "kotlin" }
@@ -49,6 +51,7 @@ r2dbc-mysql = { module = "io.asyncer:r2dbc-mysql", version.ref = "r2dbc-mysql" }
 r2dbc-postgresql = { module = "org.postgresql:r2dbc-postgresql", version.ref = "r2dbc-postgresql" }
 jsqlparser = { module = "com.github.jsqlparser:jsqlparser", version.ref = "jsqlparser" }
 calcite-core = { module = "org.apache.calcite:calcite-core", version.ref = "calcite" }
+log4k-slf4j = { module = "io.github.smyrgeorge:log4k-slf4j", version.ref = "log4k" }
 
 [plugins]
 kotlin-multiplatform = { id = "org.jetbrains.kotlin.multiplatform", version.ref = "kotlin" }
diff --git a/sqlx4k-codegen/build.gradle.kts b/sqlx4k-codegen/build.gradle.kts
@@ -12,9 +12,11 @@ kotlin {
         }
         val jvmMain by getting {
             dependencies {
+                api(project(":sqlx4k"))
                 implementation(libs.ksp)
                 implementation(libs.jsqlparser)
                 implementation(libs.calcite.core)
+                implementation(libs.log4k.slf4j)
             }
         }
     }
diff --git a/sqlx4k-codegen/src/jvmMain/kotlin/io/github/smyrgeorge/sqlx4k/processor/RepositoryProcessor.kt b/sqlx4k-codegen/src/jvmMain/kotlin/io/github/smyrgeorge/sqlx4k/processor/RepositoryProcessor.kt
@@ -16,6 +16,7 @@ import com.google.devtools.ksp.symbol.KSType
 import com.google.devtools.ksp.symbol.KSValueArgument
 import com.google.devtools.ksp.symbol.KSValueParameter
 import com.google.devtools.ksp.validate
+import io.github.smyrgeorge.sqlx4k.Statement
 import java.io.OutputStream
 
 class RepositoryProcessor(
@@ -37,7 +38,6 @@ class RepositoryProcessor(
         val repoSymbols = resolver
             .getSymbolsWithAnnotation(TypeNames.REPOSITORY_ANNOTATION)
             .filterIsInstance<KSClassDeclaration>()
-
         if (!repoSymbols.iterator().hasNext()) return emptyList()
 
         val outputPackage = options[TableProcessor.PACKAGE_OPTION]
@@ -51,14 +51,16 @@ class RepositoryProcessor(
         logger.info("[RepositoryProcessor] Validate SQL schema: $globalCheckSqlSchema")
         val schemaMigrationsPath = options[SCHEMA_MIGRATIONS_PATH_OPTION] ?: "./set-the-path-to-schema-migrations"
 
-        if (globalCheckSqlSchema) QueryValidator.load(schemaMigrationsPath)
-
-        val outputFilename = "GeneratedRepositories"
+        // Load schemas.
+        if (globalCheckSqlSchema) SqlValidator.loadSchema(schemaMigrationsPath)
 
         val file: OutputStream = codeGenerator.createNewFile(
+            // Make sure to associate the generated file with sources to keep/maintain it across incremental builds.
+            // Learn more about incremental processing in KSP from the official docs:
+            // https://kotlinlang.org/docs/ksp-incremental.html
             dependencies = Dependencies(false, *resolver.getAllFiles().toList().toTypedArray()),
             packageName = outputPackage,
-            fileName = outputFilename
+            fileName = OUTPUT_FILENAME
         )
 
         file += "// Generated by sqlx4k-codegen (RepositoryProcessor)\n"
@@ -69,22 +71,22 @@ class RepositoryProcessor(
 
         // For each repository interface, find methods annotated with @Query
         val validatedRepos = repoSymbols.filter { it.validate() }
-        validatedRepos.forEach { iface ->
-            if (iface.classKind != ClassKind.INTERFACE)
-                error("@Repository is only supported on interfaces (${iface.qualifiedName()}).")
+        validatedRepos.forEach { repo ->
+            if (repo.classKind != ClassKind.INTERFACE)
+                error("@Repository is only supported on interfaces (${repo.qualifiedName()}).")
 
             // Extract domain and mapper from @Repository annotation on the interface
-            val (domainDecl, mapperTypeName) = parseRepositoryAnnotation(iface)
+            val (domainDecl, mapperTypeName) = parseRepositoryAnnotation(repo)
 
             // Find all methods declared in the interface
-            val fnsAll = iface.declarations.filterIsInstance<KSFunctionDeclaration>().toList()
+            val fnsAll = repo.declarations.filterIsInstance<KSFunctionDeclaration>().toList()
 
             // Determine implementation class name
-            val implName = iface.simpleName() + "Impl"
-            logger.info("[RepositoryProcessor] Generating implementation object $implName for ${iface.qualifiedName()}")
+            val implName = repo.simpleName() + "Impl"
+            logger.info("[RepositoryProcessor] Generating implementation object $implName for ${repo.qualifiedName()}")
 
             // Emit class header
-            file += "\nobject $implName : ${iface.qualifiedName()} {\n"
+            file += "\nobject $implName : ${repo.qualifiedName()} {\n"
 
             // Generate @Query-based methods according to prefixes:
             // findAll/findAllBy/findOneBy/deleteBy/countBy/execute and also *All variants
@@ -172,21 +174,21 @@ class RepositoryProcessor(
      * Parses the `@Repository` annotation on a given interface and extracts the associated domain class
      * and mapper class information.
      *
-     * @param iface The class declaration of the interface annotated with `@Repository`.
+     * @param repo The class declaration of the interface annotated with `@Repository`.
      * @return A pair where the first element is the class declaration of the domain type and the second
      *         element is the fully qualified name of the mapper class.
      * @throws IllegalStateException if the `@Repository` annotation is missing, incomplete, or improperly configured.
      */
-    private fun parseRepositoryAnnotation(iface: KSClassDeclaration): Pair<KSClassDeclaration, String> {
-        fun implementsCrudRepository(iface: KSClassDeclaration): KSClassDeclaration {
+    private fun parseRepositoryAnnotation(repo: KSClassDeclaration): Pair<KSClassDeclaration, String> {
+        fun implementsCrudRepository(repo: KSClassDeclaration): KSClassDeclaration {
             // find CrudRepository<T>
-            val st = iface.superTypes.map { it.resolve() }
+            val st = repo.superTypes.map { it.resolve() }
                 .firstOrNull { it.declaration.qualifiedName() == TypeNames.CRUD_REPOSITORY }
-                ?: error("@Repository interface ${iface.qualifiedName()} must extend ${TypeNames.CRUD_REPOSITORY}<T>")
+                ?: error("@Repository interface ${repo.qualifiedName()} must extend ${TypeNames.CRUD_REPOSITORY}<T>")
             val typeArg = st.arguments.firstOrNull()?.type?.resolve()
-                ?: error("${iface.qualifiedName()} implements CrudRepository without type argument; expected CrudRepository<T>")
+                ?: error("${repo.qualifiedName()} implements CrudRepository without type argument; expected CrudRepository<T>")
             val domainDecl = typeArg.declaration as? KSClassDeclaration
-                ?: error("CrudRepository type argument must be a class on ${iface.qualifiedName()}")
+                ?: error("CrudRepository type argument must be a class on ${repo.qualifiedName()}")
             // ensure @Table
             val hasTable = domainDecl.annotations.any {
                 val qn = it.qualifiedName()
@@ -196,17 +198,17 @@ class RepositoryProcessor(
             return domainDecl
         }
 
-        val repoAnn = iface.annotations.firstOrNull { it.qualifiedName() == TypeNames.REPOSITORY_ANNOTATION }
-            ?: error("Missing @Repository annotation on interface ${iface.qualifiedName()}")
+        val repoAnn = repo.annotations.firstOrNull { it.qualifiedName() == TypeNames.REPOSITORY_ANNOTATION }
+            ?: error("Missing @Repository annotation on interface ${repo.qualifiedName()}")
 
         // Enforce that the interface extends CrudRepository<T> and derive domain from T
-        val domainDecl = implementsCrudRepository(iface)
+        val domainDecl = implementsCrudRepository(repo)
 
         val mapperArg: KSValueArgument? = repoAnn.arguments.firstOrNull { it.name?.asString() == "mapper" }
         val mapperKSType = mapperArg?.value as? KSType
-            ?: error("@Repository must declare a mapper, e.g. @Repository(mapper = FooRowMapper::class) on ${iface.qualifiedName()}")
+            ?: error("@Repository must declare a mapper, e.g. @Repository(mapper = FooRowMapper::class) on ${repo.qualifiedName()}")
         val mapperTypeName = mapperKSType.declaration.qualifiedName()
-            ?: error("Unable to resolve mapper type for ${iface.qualifiedName()}")
+            ?: error("Unable to resolve mapper type for ${repo.qualifiedName()}")
         return domainDecl to mapperTypeName
     }
 
@@ -234,14 +236,14 @@ class RepositoryProcessor(
     }
 
     /**
-     * Validates the return type of a repository method based on its prefix and ensures that it complies
+     * Validates the return type of the repository method based on its prefix and ensures that it complies
      * with the expected return type structure and repository domain type.
      *
      * @param prefix The method prefix indicating the type of operation, such as FIND_ALL, DELETE_BY, etc.
      * @param fn The function declaration representing the repository method being validated.
      * @param domainDecl The class declaration of the repository's domain type to validate against.
      */
-    private fun validateReturnTypeForPrefix(prefix: Prefix, fn: KSFunctionDeclaration, domainDecl: KSClassDeclaration) {
+    private fun validateReturnType(prefix: Prefix, fn: KSFunctionDeclaration, domainDecl: KSClassDeclaration) {
         val name = fn.simpleName()
         val returnType = fn.returnType?.resolve()
             ?: error("Unable to resolve return type for method '$name'")
@@ -310,11 +312,35 @@ class RepositoryProcessor(
         }
     }
 
+    /**
+     * Validates the parameters of a repository method against the SQL query and ensures consistency
+     * between the method signature and the query's named parameters.
+     *
+     * @param sql The SQL query string provided in the `@Query` annotation.
+     * @param fn The function declaration of the repository method being validated.
+     *           This includes information about the method name and its parameters.
+     */
+    fun validateParameters(sql: String, fn: KSFunctionDeclaration) {
+        val name = fn.simpleName()
+        val statement = Statement.create(sql)
+        if (statement.extractedPositionalParameters > 0)
+            error("Method '$name' uses positional parameters in @Query (only named parameters are supported).")
+        val parameters = fn.parameters.drop(1) // Exclude 'context' argument.
+        if (parameters.size != statement.extractedNamedParameters.size)
+            error("Method '$name' has ${parameters.size} parameters but @Query statement has ${statement.extractedNamedParameters.size} named parameters.")
+        parameters.forEach { p ->
+            val pName = p.name?.asString()
+                ?: error("All query parameters must be named when using namedParameters support")
+            if (!statement.extractedNamedParameters.contains(pName))
+                error("Method '$name' has parameter '$pName' but @Query statement does not contain a named parameter with that name.")
+        }
+    }
+
     /**
      * Emits named parameter bindings for a given list of parameters into the specified output stream.
      * This method assumes that parameters after the first one must be named and generates binding statements accordingly.
      *
-     * @param file The OutputStream where the named parameter binding statements will be written.
+     * @param file The OutputStream where the named parameter-binding statements will be written.
      * @param params A list of KSValueParameter objects representing the parameters for which bindings are generated. The first parameter is excluded from processing.
      */
     private fun emitNamedParameterBindings(file: OutputStream, params: List<KSValueParameter>) {
@@ -326,13 +352,15 @@ class RepositoryProcessor(
     }
 
     /**
-     * Emits a Kotlin method for executing a database query based on a function annotated with a custom `@Query` annotation.
-     * This method generates the implementation for the annotated function, including SQL query execution and result handling.
+     * Generates and writes the implementation for a repository method annotated with `@Query` into the provided output stream.
+     * The method performs various validations such as syntax, schema, parameter consistency, and expected return type prior to generation.
      *
-     * @param file The OutputStream where the method implementation will be written.
-     * @param fn The function declaration representing the repository method annotated with `@Query`.
-     * @param mapperTypeName The fully qualified name of the result mapper type used for mapping query results to domain objects.
-     * @param domainDecl The class declaration of the domain object type associated with the repository method.
+     * @param file The output stream where the generated method implementation will be written.
+     * @param fn The function declaration of the repository method to be emitted. This includes the method name, parameters, and annotations.
+     * @param validateSyntax A flag indicating whether the SQL query syntax should be validated before emitting the method.
+     * @param validateSchema A flag indicating whether the SQL query schema consistency should be validated before emitting the method.
+     * @param mapperTypeName The fully qualified name of the mapper type used for mapping query results to domain objects.
+     * @param domainDecl The class declaration of the domain type associated with the repository being processed.
      */
     private fun emitQueryMethod(
         file: OutputStream,
@@ -343,6 +371,7 @@ class RepositoryProcessor(
         domainDecl: KSClassDeclaration
     ) {
         val name = fn.simpleName()
+        val prefix: Prefix = parseMethodPrefix(name)
         logger.info("[RepositoryProcessor] Generating @Query method: $name")
 
         val sql: String = fn.annotations.first { it.qualifiedName() == TypeNames.QUERY_ANNOTATION }
@@ -356,13 +385,13 @@ class RepositoryProcessor(
             val pType = p.type.toString()
             "$pName: $pType"
         }
-        val prefix: Prefix = parseMethodPrefix(name)
+
         validateContextParameter(name, params)
         validateParameterArity(prefix, name, params)
-        validateReturnTypeForPrefix(prefix, fn, domainDecl)
-
-        if (validateSyntax) QueryValidator.validateQuerySyntax(fn.simpleName(), sql)
-        if (validateSchema) QueryValidator.validateQuerySchema(fn.simpleName(), sql)
+        validateParameters(sql, fn)
+        validateReturnType(prefix, fn, domainDecl)
+        if (validateSyntax) SqlValidator.validateQuerySyntax(fn.simpleName(), sql)
+        if (validateSchema) SqlValidator.validateQuerySchema(fn.simpleName(), sql)
 
         logger.info("[RepositoryProcessor] Emitting method '$name' with prefix ${prefix.name} in ${domainDecl.qualifiedName()} using mapper $mapperTypeName")
 
@@ -472,6 +501,13 @@ class RepositoryProcessor(
     private fun KSAnnotation.qualifiedName(): String? = annotationType.resolve().declaration.qualifiedName?.asString()
 
     companion object {
+        /**
+         * The default output file name used for generating repository implementations.
+         * This constant is used in the code generation process to create output files
+         * with a standardized and consistent naming convention.
+         */
+        private const val OUTPUT_FILENAME = "GeneratedRepositories"
+
         /**
          * Represents an option key used to enable or disable SQL syntax validation during the processing
          * of repository methods. Methods marked with the SQL validation flag will have their provided SQL
diff --git a/sqlx4k-codegen/src/jvmMain/kotlin/io/github/smyrgeorge/sqlx4k/processor/SqlValidator.kt b/sqlx4k-codegen/src/jvmMain/kotlin/io/github/smyrgeorge/sqlx4k/processor/SqlValidator.kt
@@ -30,7 +30,7 @@ import org.apache.calcite.sql.validate.SqlValidatorUtil
 import java.io.File
 import java.util.*
 
-object QueryValidator {
+object SqlValidator {
     private lateinit var tables: List<TableDef>
     private lateinit var validator: SqlValidator
 
@@ -63,7 +63,7 @@ object QueryValidator {
         }
     }
 
-    fun load(path: String) {
+    fun loadSchema(path: String) {
         fun parseFileName(name: String): Long {
             val fileNamePattern = Regex("""^\s*(\d+)_([A-Za-z0-9._-]+)\.sql\s*$""")
             val name = name.trim()
@@ -129,8 +129,8 @@ object QueryValidator {
             }
         }
 
-        this.tables = schema.values.toList()
-        this.validator = createCalciteValidator()
+        tables = schema.values.toList()
+        validator = createCalciteValidator()
     }
 
     private fun createCalciteValidator(): SqlValidator {
diff --git a/sqlx4k-codegen/src/jvmMain/kotlin/io/github/smyrgeorge/sqlx4k/processor/TableProcessor.kt b/sqlx4k-codegen/src/jvmMain/kotlin/io/github/smyrgeorge/sqlx4k/processor/TableProcessor.kt
@@ -1,7 +1,16 @@
 package io.github.smyrgeorge.sqlx4k.processor
 
-import com.google.devtools.ksp.processing.*
-import com.google.devtools.ksp.symbol.*
+import com.google.devtools.ksp.processing.CodeGenerator
+import com.google.devtools.ksp.processing.Dependencies
+import com.google.devtools.ksp.processing.KSPLogger
+import com.google.devtools.ksp.processing.Resolver
+import com.google.devtools.ksp.processing.SymbolProcessor
+import com.google.devtools.ksp.symbol.KSAnnotated
+import com.google.devtools.ksp.symbol.KSAnnotation
+import com.google.devtools.ksp.symbol.KSClassDeclaration
+import com.google.devtools.ksp.symbol.KSPropertyDeclaration
+import com.google.devtools.ksp.symbol.KSValueArgument
+import com.google.devtools.ksp.symbol.KSVisitorVoid
 import com.google.devtools.ksp.validate
 import java.io.OutputStream
 
@@ -20,11 +29,9 @@ class TableProcessor(
         val symbols = resolver
             .getSymbolsWithAnnotation(TypeNames.TABLE_ANNOTATION)
             .filterIsInstance<KSClassDeclaration>()
-
         if (!symbols.iterator().hasNext()) return emptyList()
 
         val outputPackage = options[PACKAGE_OPTION] ?: error("Missing $PACKAGE_OPTION option")
-        val outputFilename = "GeneratedQueries"
 
         logger.info("sqlx4k-codegen: TableProcessor dialect = $dialect")
 
@@ -34,7 +41,7 @@ class TableProcessor(
             // https://kotlinlang.org/docs/ksp-incremental.html
             dependencies = Dependencies(false, *resolver.getAllFiles().toList().toTypedArray()),
             packageName = outputPackage,
-            fileName = outputFilename
+            fileName = OUTPUT_FILENAME
         )
 
         file += "// Generated by sqlx4k-codegen (TableProcessor)\n"
@@ -267,6 +274,13 @@ class TableProcessor(
     }
 
     companion object {
+        /**
+         * The default filename used for storing or generating query-related output files.
+         * Typically used within the code generation process to standardize the naming
+         * of generated query files.
+         */
+        private const val OUTPUT_FILENAME = "GeneratedQueries"
+
         /**
          * Key used to specify the package name for the generated output classes.
          */
diff --git a/sqlx4k/src/commonMain/kotlin/io/github/smyrgeorge/sqlx4k/Statement.kt b/sqlx4k/src/commonMain/kotlin/io/github/smyrgeorge/sqlx4k/Statement.kt
@@ -10,6 +10,18 @@ import kotlin.reflect.KClass
  */
 interface Statement {
 
+    /**
+     * A set containing the names of all named parameters extracted from the SQL statement.
+     * It is populated using a parser that skips over string literals, comments, and
+     * PostgreSQL dollar-quoted strings.
+     */
+    val extractedNamedParameters: Set<String>
+
+    /**
+     * The count of positional parameter placeholders ('?') extracted from the SQL query.
+     */
+    val extractedPositionalParameters: Int
+
     /**
      * Binds a value to a positional parameter in the statement based on the given index.
      *
diff --git a/sqlx4k/src/commonMain/kotlin/io/github/smyrgeorge/sqlx4k/impl/statement/AbstractStatement.kt b/sqlx4k/src/commonMain/kotlin/io/github/smyrgeorge/sqlx4k/impl/statement/AbstractStatement.kt

Original file line number	Diff line number	Diff line change
`@@ -12,9 +12,11 @@ kotlin {`
`12`	`12`	`}`
`13`	`13`	`val jvmMain by getting {`
`14`	`14`	`dependencies {`
	`15`	`+ api(project(":sqlx4k"))`
`15`	`16`	`implementation(libs.ksp)`
`16`	`17`	`implementation(libs.jsqlparser)`
`17`	`18`	`implementation(libs.calcite.core)`
	`19`	`+ implementation(libs.log4k.slf4j)`
`18`	`20`	`}`
`19`	`21`	`}`
`20`	`22`	`}`
Original file line number	Diff line number	Diff line change
`@@ -30,7 +30,7 @@ import org.apache.calcite.sql.validate.SqlValidatorUtil`
`30`	`30`	`import java.io.File`
`31`	`31`	`import java.util.*`
`32`	`32`
`33`		`-object QueryValidator {`
	`33`	`+object SqlValidator {`
`34`	`34`	`private lateinit var tables: List<TableDef>`
`35`	`35`	`private lateinit var validator: SqlValidator`
`36`	`36`
`@@ -63,7 +63,7 @@ object QueryValidator {`
`63`	`63`	`}`
`64`	`64`	`}`
`65`	`65`
`66`		`- fun load(path: String) {`
	`66`	`+ fun loadSchema(path: String) {`
`67`	`67`	`fun parseFileName(name: String): Long {`
`68`	`68`	`val fileNamePattern = Regex("""^\s(\d+)_([A-Za-z0-9._-]+)\.sql\s$""")`
`69`	`69`	`val name = name.trim()`
`@@ -129,8 +129,8 @@ object QueryValidator {`
`129`	`129`	`}`
`130`	`130`	`}`
`131`	`131`
`132`		`- this.tables = schema.values.toList()`
`133`		`- this.validator = createCalciteValidator()`
	`132`	`+ tables = schema.values.toList()`
	`133`	`+ validator = createCalciteValidator()`
`134`	`134`	`}`
`135`	`135`
`136`	`136`	`private fun createCalciteValidator(): SqlValidator {`