[data] introduce Environment and improve KyoException

kyo-core/jvm/src/main/scala/kyo/StreamCompression.scala

@@ -11,12 +11,7 @@ import scala.annotation.tailrec
 
 object StreamCompression:
 
-    final class StreamCompressionException(reason: String | Throwable)(using Frame) extends KyoException(
-            message = reason match
-                case string: String => Text(string)
-                case _: Throwable   => null,
-            cause = reason
-        )
+    final class StreamCompressionException(cause: Text | Throwable)(using Frame) extends KyoException("", cause)
 
     enum CompressionLevel(val value: Int) derives CanEqual:
         case Default         extends CompressionLevel(-1)

kyo-data/shared/src/main/scala/kyo/KyoException.scala

@@ -1,34 +1,70 @@
 package kyo
 
+import KyoException.maxMessageLength
 import kyo.*
 import kyo.Ansi.*
+import kyo.internal.Environment
 import scala.util.control.NoStackTrace
 
+/** Kyo's base exception class that provides enhanced error reporting and context.
+  *
+  * The exception's behavior changes based on the environment:
+  *   - In development: Provides detailed, ANSI-colored error messages with context
+  *   - In production: Returns minimal error messages for cleaner logs
+  *
+  * @param message
+  *   The primary error message
+  * @param cause
+  *   Either a Text explanation or a Throwable that caused this exception
+  * @param frame
+  *   Implicit Frame providing context about where the exception was created
+  */
 class KyoException private[kyo] (
-    message: Text | Null = null,
-    cause: Text | Throwable | Null = null
+    message: Text = "",
+    cause: Text | Throwable = ""
 )(using val frame: Frame) extends Exception(
-        Option(message) match
-            case Some(message) => message.toString;
-            case _             => null,
+        message.toString,
         cause match
-            case cause: Throwable => cause;
+            case cause: Throwable => cause
             case _                => null
     ) with NoStackTrace:
 
+    /** Returns the underlying cause of this exception. Overriding this method is important for performance since the method is synchronized
+      * in the super classes.
+      *
+      * @return
+      *   The Throwable cause if one was provided, null otherwise
+      */
     override def getCause(): Throwable =
         cause match
             case cause: Throwable => cause
             case _                => null
 
+    /** Formats and returns the exception message.
+      *
+      * In production mode, returns only the cause message if present, or null if no cause message was provided.
+      *
+      * @return
+      *   The formatted exception message
+      */
     override def getMessage(): String =
         val detail =
             cause match
                 case _: Throwable           => Absent
-                case cause: Text @unchecked => Maybe(cause)
+                case cause: Text @unchecked => Maybe(cause.take(maxMessageLength))
 
-        val msg = frame.render(("⚠️ KyoException".red.bold :: Maybe(message).toList ::: detail.toList).map(_.show)*)
-        s"\n$msg\n"
+        if Environment.isDevelopment then
+            val msg = frame.render(
+                ("⚠️ KyoException".red.bold :: Maybe(message).toList ::: detail.toList)
+                    .map(_.show)*
+            )
+            s"\n$msg\n"
+        else
+            detail.map(_.toString).getOrElse(null)
+        end if
     end getMessage
-
 end KyoException
+
+object KyoException:
+    /** Maximum length for error messages to prevent excessive output. */
+    val maxMessageLength = 1000

kyo-data/shared/src/main/scala/kyo/internal/Environment.scala

@@ -0,0 +1,37 @@
+package kyo.internal
+
+/** Environment detection utility.
+  *
+  * Provides functionality to detect whether the JVM is running in a development environment. This information is used to control the
+  * verbosity of error messages and debugging information in Kyo's implementations.
+  *
+  * The development mode can be controlled in two ways:
+  *   1. Explicitly via the system property "-Dkyo.development=true"
+  *   2. Automatically by detecting SBT in the classpath
+  */
+private[kyo] object Environment:
+
+    /** Determines if the execution is a development environment.
+      *
+      * This method checks the following conditions in order:
+      *
+      *   1. If system property "kyo.development" exists:
+      *      - Returns true if the property value is "true" (case insensitive)
+      *      - Returns false if the property value is anything else
+      *   2. If the property doesn't exist:
+      *      - Returns true if SBT is detected in the classpath (contains "org.scala-sbt")
+      *      - Returns false otherwise
+      *
+      * @return
+      *   true if running in a development environment, false otherwise
+      */
+    val isDevelopment: Boolean = inferIsDevelopment()
+
+    private[internal] def inferIsDevelopment(): Boolean =
+        sys.props.get("kyo.development").map(_.toLowerCase) match
+            case Some("true") => true
+            case Some(_)      => false
+            case None =>
+                sys.props.get("java.class.path").exists(_.contains("org.scala-sbt"))
+
+end Environment

kyo-data/shared/src/test/scala/kyo/internal/EnvironmentTest.scala

@@ -0,0 +1,25 @@
+package kyo.internal
+
+import org.scalatest.freespec.AnyFreeSpec
+import org.scalatest.matchers.should.Matchers
+
+class EnvironmentTest extends AnyFreeSpec with Matchers:
+
+    "infers as development" - {
+        "if system property is enabled, which should be the case in this test execution" in {
+            System.setProperty("kyo.development", "true")
+            assert(Environment.inferIsDevelopment())
+        }
+    }
+
+    "doesn't infer as development" - {
+        "if system property is false" in {
+            System.setProperty("kyo.development", "false")
+            assert(!Environment.inferIsDevelopment())
+        }
+        "if system property is invalid" in {
+            System.setProperty("kyo.development", "blah")
+            assert(!Environment.inferIsDevelopment())
+        }
+    }
+end EnvironmentTest