feat(watermarker): add Trendmark validation option for increased robustness (#214)

Author: Schiphorst-ISST

docs/docs/03-usage/10-watermarker/index.mdx

@@ -64,9 +64,14 @@ returned
 = [**true**/false]: when true only the most frequent Watermark is returned
     - if multiple Watermarks appear with the same (highest) frequency a warning is returned with the Watermarks
     - this is separate from the squashing above, duplicates of the most frequent Watermark(s) are still returned if squash = false
-- [`ErrorOnInvalidUTF8`](https://github.com/FraunhoferISST/TREND/blob/eb5f3b62bc31a63f985fa87c01522281adcb7c3e/watermarker/src/commonMain/kotlin/watermarks/TextWatermark.kt#L123)
+- [`errorOnInvalidUTF8`](https://github.com/FraunhoferISST/TREND/blob/eb5f3b62bc31a63f985fa87c01522281adcb7c3e/watermarker/src/commonMain/kotlin/watermarks/TextWatermark.kt#L123)
 = [true/**false**]: For functions returning TextWatermarks only, when true throws a
 CharacterCodingException when encountering malformed UTF8 Bytes
+- [`validateAll`](https://github.com/FraunhoferISST/TREND/blob/8b47f1a373769656506a615436b558e362a8952c/watermarker/src/commonMain/kotlin/watermarks/Trendmark.kt#L56)
+= [**true**/false]: For functions returning Trendmarks only, when true calls the
+Trendmark validate() function, which will check for valid characteristics depending on the
+Trendmark type. See the [Trendmark](../../development/watermarker/trendmark) section for more
+details.
 
 ## Kotlin Library: Special Characteristics
 Kotlin uses so-called

watermarker/src/commonMain/kotlin/Watermarker.kt

@@ -178,6 +178,7 @@ open class Watermarker {
      *
      * When [squash] is true: watermarks with the same content are merged.
      * When [singleWatermark] is true: only the most frequent watermark is returned.
+     * When [validateAll] is true: All resulting Trendmarks are validated to check for errors.
      *
      * Returns a warning if some watermarks could not be converted to Trendmarks.
      * Returns an error if no watermark could be converted to a Trendmark.
@@ -186,8 +187,19 @@ open class Watermarker {
         text: String,
         squash: Boolean = true,
         singleWatermark: Boolean = true,
-    ): Result<List<Trendmark>> =
-        textGetWatermarks(text, squash, singleWatermark).toTrendmarks("$SOURCE.textGetTrendmarks")
+        validateAll: Boolean = true,
+    ): Result<List<Trendmark>> {
+        val result =
+            textGetWatermarks(text, squash, singleWatermark)
+                .toTrendmarks("$SOURCE.textGetTrendmarks")
+        if (validateAll && result.hasValue && result.value!!.isNotEmpty()) {
+            for (trendmark in result.value) {
+                val validationStatus = trendmark.validate()
+                result.appendStatus(validationStatus)
+            }
+        }
+        return result
+    }
 
     /**
      * Returns all watermarks in [text] as TextWatermarks.

watermarker/src/jvmMain/kotlin/JvmWatermarker.kt

@@ -215,6 +215,7 @@ class JvmWatermarker : Watermarker() {
      * When [fileType] is null the type is taken from [source]'s extension.
      * When [squash] is true: watermarks with the same content are merged.
      * When [singleWatermark] is true: only the most frequent watermark is returned.
+     * When [validateAll] is true: All resulting Trendmarks are validated to check for errors.
      *
      * Returns a warning if some watermarks could not be converted to Trendmarks.
      * Returns an error if no watermark could be converted to a Trendmark.
@@ -224,8 +225,18 @@ class JvmWatermarker : Watermarker() {
         fileType: String? = null,
         squash: Boolean = true,
         singleWatermark: Boolean = true,
+        validateAll: Boolean = true,
     ): Result<List<Trendmark>> {
-        return getWatermarks(source, fileType, squash, singleWatermark).toTrendmarks(SOURCE)
+        val result = getWatermarks(source, fileType, squash, singleWatermark).toTrendmarks(SOURCE)
+
+        if (validateAll && result.hasValue && result.value!!.isNotEmpty()) {
+            for (trendmark in result.value) {
+                val validationStatus = trendmark.validate()
+                result.appendStatus(validationStatus)
+            }
+        }
+
+        return result
     }
 
     /**
@@ -260,6 +271,7 @@ class JvmWatermarker : Watermarker() {
     /**
      * Removes all watermarks in [source] and returns them.
      *
+     * When [singleWatermark] is true: only the most frequent watermark is returned.
      * When [fileType] is null the type is taken from [source]'s extension.
      */
     fun removeWatermarks(