Support custom message validators

buildSrc/src/main/kotlin/io/spine/dependency/Dependency.kt

@@ -58,7 +58,7 @@ abstract class Dependency {
     /**
      * The [modules] given with the [version].
      */
-    final val artifacts: Map<String, String> by lazy {
+    val artifacts: Map<String, String> by lazy {
         modules.associateWith { "$it:$version" }
     }
 
@@ -114,3 +114,19 @@ private fun ResolutionStrategy.forceWithLogging(
     force(artifact)
     project.log { "Forced the version of `$artifact` in " + configuration.diagSuffix(project) }
 }
+
+/**
+ * Obtains full Maven coordinates for the requested [module].
+ *
+ * This extension allows referencing properties of the [Dependency],
+ * upon which it is invoked.
+ *
+ * An example usage:
+ *
+ * ```
+ * // Supposing there is `Ksp.symbolProcessingApi: String` property declared.
+ * Ksp.artifact { symbolProcessingApi }
+ * ```
+ */
+fun <T : Dependency> T.artifact(module: T.() -> String): String =
+    artifact(module())

buildSrc/src/main/kotlin/io/spine/dependency/test/KotlinCompileTesting.kt

@@ -33,7 +33,7 @@ package io.spine.dependency.test
  */
 @Suppress("unused", "ConstPropertyName")
 object KotlinCompileTesting {
-    private const val version = "0.7.0"
+    private const val version = "0.7.1"
     private const val group = "dev.zacsweers.kctfork"
     const val libCore = "$group:core:$version"
     const val libKsp = "$group:ksp:$version"

buildSrc/src/main/kotlin/module.gradle.kts

@@ -28,6 +28,7 @@ import io.spine.dependency.boms.BomsPlugin
 import io.spine.dependency.build.Dokka
 import io.spine.dependency.build.ErrorProne
 import io.spine.dependency.build.JSpecify
+import io.spine.dependency.build.Ksp
 import io.spine.dependency.lib.Grpc
 import io.spine.dependency.lib.Kotlin
 import io.spine.dependency.lib.Protobuf
@@ -144,8 +145,10 @@ fun Module.forceConfigurations() {
         all {
             resolutionStrategy {
                 Grpc.forceArtifacts(project, this@all, this@resolutionStrategy)
+                Ksp.forceArtifacts(project, this@all, this@resolutionStrategy)
                 force(
                     Kotlin.bom,
+                    Kotlin.Compiler.embeddable,
                     Reflect.lib,
                     Base.lib,
                     Protobuf.compiler,

java-api/src/main/kotlin/io/spine/validation/api/DetectedViolation.kt

@@ -0,0 +1,65 @@
+/*
+ * Copyright 2025, TeamDev. All rights reserved.
+ *
+ * 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
+ *
+ * Redistribution and use in source and/or binary forms, with or without
+ * modification, must retain the above copyright notice and the following
+ * disclaimer.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+package io.spine.validation.api
+
+import io.spine.base.FieldPath
+import io.spine.validate.TemplateString
+
+/**
+ * Abstract base for violations detected by [MessageValidator]s.
+ *
+ * @param message The error message describing the violation.
+ * @param fieldPath The path to the field where the violation occurred, if applicable.
+ * @param fieldValue The field value that caused the violation, if any.
+ */
+public abstract class DetectedViolation(
+    public val message: TemplateString,
+    public val fieldPath: FieldPath?,
+    public val fieldValue: Any?,
+)
+
+/**
+ * A violation tied to a specific field in a message.
+ *
+ * @param message The error message describing the violation.
+ * @param fieldPath The path to the field where the violation occurred.
+ * @param fieldValue The field value that caused the violation, if any.
+ */
+public class FieldViolation(
+    message: TemplateString,
+    fieldPath: FieldPath,
+    fieldValue: Any? = null,
+) : DetectedViolation(message, fieldPath, fieldValue)
+
+/**
+ * A violation related to the message level (not tied to a specific field).
+ *
+ * @param message The error message describing the violation.
+ */
+public class MessageViolation(
+    message: TemplateString
+) : DetectedViolation(message, fieldPath = null, fieldValue = null)

java-api/src/main/kotlin/io/spine/validation/api/DiscoveredValidators.kt

@@ -0,0 +1,46 @@
+/*
+ * Copyright 2025, TeamDev. All rights reserved.
+ *
+ * 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
+ *
+ * Redistribution and use in source and/or binary forms, with or without
+ * modification, must retain the above copyright notice and the following
+ * disclaimer.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+package io.spine.validation.api
+
+import io.spine.annotation.Internal
+
+/**
+ * Holds a path to a file with the discovered validators.
+ *
+ * The KSP processor generates a resource file using this path.
+ * Then, the Java codegen plugin picks up this file.
+ */
+@Internal
+public object DiscoveredValidators {
+
+    /**
+     * The path to the file with the discovered message validators.
+     *
+     * The path is relative to the output directory of the KSP processor.
+     */
+   public const val RESOURCES_LOCATION: String = "spine/validation/message-validators"
+}

java-api/src/main/kotlin/io/spine/validation/api/MessageValidator.kt

@@ -0,0 +1,132 @@
+/*
+ * Copyright 2025, TeamDev. All rights reserved.
+ *
+ * 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
+ *
+ * Redistribution and use in source and/or binary forms, with or without
+ * modification, must retain the above copyright notice and the following
+ * disclaimer.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+package io.spine.validation.api
+
+import com.google.protobuf.Message
+import io.spine.annotation.SPI
+
+/**
+ * A custom validator for an external Protobuf message of type [M].
+ *
+ * ## Notation of external and local messages
+ *
+ * **Local messages** are message types for which end-users generate and control
+ * the Java/Kotlin classes by compiling the corresponding `.proto` definitions
+ * within their own codebase. For such messages, the validation library allows
+ * declaring validation constraints and enforces them with the generated code.
+ *
+ * **External messages** are message types for which end-users do not generate or control
+ * the Java/Kotlin classes (for example, pre-compiled classes from third-party dependencies).
+ * Because these classes are already generated, users cannot modify the underlying `.proto`
+ * definitions and add validation options at compile time. There is no control of
+ * the code generation.
+ *
+ * ## Validation of external messages
+ *
+ * The validation library provides a customization mechanism that allows validating
+ * of the external messages, **which are embedded within local messages**.
+ * Implement this interface and annotate the implementing class with
+ * the [@Validator][Validator] annotation, specifying the type of the message to validate.
+ *
+ * For each field of type [M] within any local message, the library will invoke
+ * the [MessageValidator.validate] method when validating the local message.
+ *
+ * The following Protobuf field types are supported:
+ *
+ * 1. Singular fields of type [M].
+ * 2. Repeated field of type [M].
+ * 3. Map field with values of type [M].
+ *
+ * An example of the validator declaration for the `Earphones` message:
+ *
+ * ```kotlin
+ * @Validator(Earphones::class)
+ * public class EarphonesValidator : MessageValidator<Earphones> {
+ *     public override fun validate(message: Earphones): List<DetectedViolation> {
+ *         return emptyList() // Always valid.
+ *     }
+ * }
+ * ```
+ *
+ * Please note that standalone instances of [M] and fields of [M] type that occur in
+ * other external messages **will not be validated**.
+ *
+ * Consider the following example:
+ *
+ * ```proto
+ * // Brings the `Earphones` message from dependencies.
+ * // Suppose we don't control the generated code of declarations from this file.
+ * import "earphones.proto";
+ *
+ * // A locally-declared message.
+ * message WorkingSetup {
+ *
+ *     // The field of external message type.
+ *     Earphones earphones = 1;
+ * }
+ * ```
+ *
+ * Supposing that the validation library applied to the module where both `WorkingSetup`
+ * and `EarphonesValidator` classes are declared, then the generated code of `WorkingSetup`
+ * will apple the validator to each instance passed to the `WorkingSetup.earphones` field.
+ *
+ * ## Implementation
+ *
+ * The message validator does not have restrictions upon how exactly the message
+ * must be validated. It can validate a particular field, several fields,
+ * the whole message instance (for example, checking the field relations),
+ * and perform a deep validation.
+ *
+ * It is a responsibility of the validator to provide the correct instances
+ * of [DetectedViolation]. Before reporting to the user, the validation library
+ * converts [DetectedViolation] to a [ConstraintViolation][io.spine.validate.ConstraintViolation].
+ * Returning of an empty list of violations means that the passed message is valid.
+ *
+ * Please keep in mind that for each invocation a new instance of [MessageValidator]
+ * is created. Every implementation of [MessageValidator] must have a public,
+ * no-args constructor.
+ *
+ * An implementation of [MessageValidator] will be rejected by the validation library
+ * in the following cases:
+ *
+ * 1) It is used to validate a local message. Only external messages are allowed
+ *    to have a validator.
+ * 2) There already exists a validator for the specified message type. Having several
+ *    validators for the same message type is prohibited.
+ *
+ * @param M the type of Protobuf [Message] being validated.
+ */
+@SPI
+public interface MessageValidator<M : Message> {
+
+    /**
+     * Validates the given [message].
+     *
+     * @return the detected violations or empty list.
+     */
+    public fun validate(message: M): List<DetectedViolation>
+}

java-api/src/main/kotlin/io/spine/validation/api/Validator.kt

@@ -0,0 +1,55 @@
+/*
+ * Copyright 2025, TeamDev. All rights reserved.
+ *
+ * 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
+ *
+ * Redistribution and use in source and/or binary forms, with or without
+ * modification, must retain the above copyright notice and the following
+ * disclaimer.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+package io.spine.validation.api
+
+import com.google.protobuf.Message
+import kotlin.annotation.AnnotationRetention.SOURCE
+import kotlin.annotation.AnnotationTarget.CLASS
+import kotlin.reflect.KClass
+
+/**
+ * Marks the class as a message validator.
+ *
+ * Applying this annotation to an implementation of [MessageValidator]
+ * makes the class visible to the validation library.
+ *
+ * Please note that the following requirements are imposed to the marked class:
+ *
+ * 1. The class must implement the [MessageValidator] interface.
+ * 2. The class must have a public, no-args constructor.
+ * 3. The class cannot be `inner`, but nested classes are allowed.
+ * 4. The message type of [Validator.value] and [MessageValidator] must match.
+ */
+@Target(CLASS)
+@Retention(SOURCE)
+public annotation class Validator(
+
+    /**
+     * The class of the validated external message.
+     */
+    val value: KClass<out Message>
+)

java-api/src/main/kotlin/io/spine/validation/api/expression/FieldPaths.kt

@@ -26,6 +26,7 @@
 
 package io.spine.validation.api.expression
 
+import com.google.protobuf.Message
 import io.spine.base.FieldPath
 import io.spine.protodata.ast.FieldName
 import io.spine.protodata.ast.OneofName
@@ -53,6 +54,16 @@ public fun Expression<FieldPath>.resolve(field: FieldName): Expression<FieldPath
         .chainAdd("field_name", StringLiteral(field.value))
         .chainBuild()
 
+/**
+ * Returns an expression that merges the provided [FieldPath] expression into this one.
+ *
+ * To perform merging, this method uses the [Message.Builder.mergeFrom] method.
+ */
+public fun Expression<FieldPath>.mergeFrom(other: Expression<FieldPath>): Expression<FieldPath> =
+    toBuilder()
+        .chain<Message.Builder>("mergeFrom", other)
+        .chainBuild()
+
 /**
  * Returns an expression that yields a new instance of [FieldPath] by appending
  * the provided [oneof] group name to this parental [FieldPath] expression.