Annotate Result#{value,error} direct access as unsafe

Requires consumers to @OptIn to accessing the 'value' and 'error'
properties directly, encouraging them to otherwise use library functions
such as mapBoth.

Closes #123, #104

Author: hoc081098

kotlin-result-coroutines/src/commonMain/kotlin/com/github/michaelbull/result/coroutines/CoroutineBinding.kt

@@ -2,6 +2,7 @@ package com.github.michaelbull.result.coroutines
 
 import com.github.michaelbull.result.Ok
 import com.github.michaelbull.result.Result
+import com.github.michaelbull.result.annotation.UnsafeResultValueAccess
 import com.github.michaelbull.result.asErr
 import com.github.michaelbull.result.binding
 import kotlinx.coroutines.CancellationException
@@ -73,6 +74,7 @@ internal class CoroutineBindingScopeImpl<E>(
     private val mutex = Mutex()
     var result: Result<Nothing, E>? = null
 
+    @OptIn(UnsafeResultValueAccess::class)
     override suspend fun <V> Result<V, E>.bind(): V {
         return if (isOk) {
             value

kotlin-result/build.gradle.kts

@@ -5,4 +5,9 @@ plugins {
 
 kotlin {
     explicitApi()
+
+    compilerOptions {
+        optIn.add("com.github.michaelbull.result.annotation.UnsafeResultValueAccess")
+        optIn.add("com.github.michaelbull.result.annotation.UnsafeResultErrorAccess")
+    }
 }

kotlin-result/src/commonMain/kotlin/com/github/michaelbull/result/Result.kt

@@ -1,5 +1,7 @@
 package com.github.michaelbull.result
 
+import com.github.michaelbull.result.annotation.UnsafeResultErrorAccess
+import com.github.michaelbull.result.annotation.UnsafeResultValueAccess
 import kotlin.jvm.JvmInline
 
 /**
@@ -52,10 +54,12 @@ public value class Result<out V, out E> internal constructor(
 ) {
 
     @Suppress("UNCHECKED_CAST")
+    @UnsafeResultValueAccess
     public val value: V
         get() = inlineValue as V
 
     @Suppress("UNCHECKED_CAST")
+    @UnsafeResultErrorAccess
     public val error: E
         get() = (inlineValue as Failure<E>).error
 

kotlin-result/src/commonMain/kotlin/com/github/michaelbull/result/annotation/UnsafeResultErrorAccess.kt

@@ -0,0 +1,25 @@
+package com.github.michaelbull.result.annotation
+
+import com.github.michaelbull.result.Err
+import com.github.michaelbull.result.Result
+import com.github.michaelbull.result.mapBoth
+import kotlin.RequiresOptIn.Level.ERROR
+import kotlin.annotation.AnnotationRetention.BINARY
+import kotlin.annotation.AnnotationTarget.PROPERTY
+
+/**
+ * Marks access to [Result.error] as unsafe. The [Result] must be guaranteed to be [Err].
+ *
+ * Ensure that you verify the state of the [Result] by using [Result.isErr] before accessing its
+ * [Result.error].
+ *
+ * Alternatively, consider using [mapBoth] to safely handle the result.
+ */
+@RequiresOptIn(
+    level = ERROR,
+    message = "Accessing `Result.error` without an explicit `Result.isErr` check is unsafe. Opt-in only when the result is guaranteed to be `Err`.",
+)
+@Retention(BINARY)
+@Target(PROPERTY)
+@MustBeDocumented
+public annotation class UnsafeResultErrorAccess

kotlin-result/src/commonMain/kotlin/com/github/michaelbull/result/annotation/UnsafeResultValueAccess.kt

@@ -0,0 +1,25 @@
+package com.github.michaelbull.result.annotation
+
+import com.github.michaelbull.result.Ok
+import com.github.michaelbull.result.Result
+import com.github.michaelbull.result.mapBoth
+import kotlin.RequiresOptIn.Level.ERROR
+import kotlin.annotation.AnnotationRetention.BINARY
+import kotlin.annotation.AnnotationTarget.PROPERTY
+
+/**
+ * Marks access to [Result.value] as unsafe. The [Result] must be guaranteed to be [Ok].
+ *
+ * Ensure that you verify the state of the [Result] by using [Result.isOk] before accessing its
+ * [Result.value].
+ *
+ * Alternatively, consider using [mapBoth] to safely handle the result.
+ */
+@RequiresOptIn(
+    level = ERROR,
+    message = "Accessing `Result.value` without an explicit `Result.isOk` check is unsafe. Opt-in only when the result is guaranteed to be `Ok`.",
+)
+@Retention(BINARY)
+@Target(PROPERTY)
+@MustBeDocumented
+public annotation class UnsafeResultValueAccess