fix: Fix non local return in getDescriptionFromAnnotation (#269)

Author: kpavlov

Makefile

@@ -24,6 +24,11 @@ scan:
 	@./gradlew clean kotlinWasmUpgradePackageLock kotlinUpgradePackageLock build --scan --rerun-tasks
 	@echo "✅ Build with scan is complete!"
 
+.PHONY: apidump
+apidump:
+	@echo "🪏 API dump..."
+	@./gradlew updateLegacyAbi
+
 .PHONY: apidocs
 apidocs:
 	@echo "📚 Generating API documentation..."

README.md

@@ -89,7 +89,7 @@ Quick Links:
 
 ## Key Features
 
-**Dual Generation Modes:**
+**Generation Modes:**
 
 - **Compile-time (KSP)**: Zero runtime overhead, multiplatform, for your annotated classes
 - **Runtime (Reflection)**: JVM-only, for any class including third-party libraries
@@ -104,22 +104,22 @@ Quick Links:
 **Flexible Annotation Support:**
 
 - Recognizes `@Description`, `@LLMDescription`, `@JsonPropertyDescription`, `@P`, and more
-- Recognizes KDoc
+- Recognizes KDoc (KSP compile-time only)
 - Works with annotations from Jackson, LangChain4j, Koog without code changes
 
 **Comprehensive Type Support:**
 
 - **Enums, collections, maps, nested objects, nullability, generics** (with star-projection)
 - **Sealed class hierarchies** with automatic `oneOf` generation and discriminator field
 - **Union types** for nullable parameters (`["string", "null"]`)
-- **Type constraints** (min/max, patterns, formats)
+- **Type constraints** (min/max, patterns, formats) via the JSON Schema DSL
 - **Default values** (compile-time: tracked but not extracted; runtime: fully extracted)
 - **`$ref`/`$defs` deduplication**: named types appear once in `$defs` and are referenced everywhere via `$ref`
 - **`kotlin.Any`**: maps to the empty schema `{}` (accepts any JSON value)
 
 **Developer Experience:**
 
-- Gradle plugin for one-line setup
+- Gradle plugin for one-line setup (experimental)
 - Type-safe Kotlin DSL for programmatic schema construction
 - Works everywhere: JVM, JS, iOS, macOS, Wasm
 
@@ -157,7 +157,7 @@ This library solves three key challenges:
 | **Class must be `@Serializable`** |               No                |                      Yes                       |                         No                          |
 | **Annotate class with `@Schema`** |            Required             |                  Not required                  |                    Not required                     |
 | **KDoc extracted to description** |                ✅                |                       ❌                        |                          ❌                          |
-| **Extract data class defaults**   |                ❌                |                       ❌                        |                          ✅                          |
+| **Extract default values**        |                ❌                |                       ❌                        |                          ✅                          |
 | **Third-party classes**           |                ❌                |            ✅ (only `@Serializable`)            |                   ✅ any JVM class                   |
 
 - **[Pick KSP](docs/ksp.md)** when you own the classes, want zero runtime overhead, and target Multiplatform or need KDoc
@@ -1297,13 +1297,12 @@ data class Product(
 
 ### Precedence Rules
 
-If multiple description annotations are present on the same element, the library uses this precedence order:
+If multiple description annotations are present on the same element, the **first matching annotation in source-code
+order** wins. There is no special priority for `@Description` over other recognized annotations — whichever recognized
+annotation appears first on the declaration is used.
 
-1. `@Description` (kotlinx-schema's own annotation)
-2. Other annotations in alphabetical order by simple name
-
-**Tip**: For best compatibility, prefer `@Description` from kotlinx-schema when writing new code, but existing
-annotations from other libraries work seamlessly.
+**Tip**: For predictability, place only one description annotation per element. If you use `@Description` from
+kotlinx-schema alongside another recognized annotation, put `@Description` first in source order to ensure it wins.
 
 ## JSON Schema DSL
 

docs/build.gradle.kts

@@ -14,6 +14,7 @@ dependencies {
     implementation(project(":kotlinx-schema-annotations"))
     implementation(project(":kotlinx-schema-generator-json"))
     implementation(libs.kotlinx.serialization.json)
+    implementation(libs.kotest.assertions.json)
 
     dokka(project(":kotlinx-schema-annotations"))
     dokka(project(":kotlinx-schema-generator-core"))

kotlinx-schema-generator-core/src/commonMain/kotlin/kotlinx/schema/generator/core/ir/Introspections.kt

@@ -93,6 +93,16 @@ public object Introspections {
      * // description == "User's email address"
      * ```
      *
+     * ## Attribute ordering
+     *
+     * When multiple parameters of the annotation match [descriptionValueAttributes] (e.g., an
+     * annotation with both `value` and `description` fields), the **first non-empty string value**
+     * in the provided `annotationArguments` list is returned. The ordering of
+     * `annotationArguments` is determined by the caller (typically the order in which
+     * `annotationClass.members` enumerates properties via Kotlin reflection, which is not
+     * specified by the Kotlin language and may vary across JVM implementations). In practice this
+     * is only relevant when both fields are non-empty simultaneously, which is an unusual usage.
+     *
      * @param annotationName The simple name of the annotation to inspect (e.g., "Description", "P")
      * @param annotationArguments List of key-value pairs representing the annotation's parameters
      * @return The description text if found, or null if the annotation is not recognized or
@@ -106,10 +116,7 @@ public object Introspections {
         if (annotationName.lowercase() in descriptionAnnotationNames) {
             annotationArguments
                 .filter { it.first.lowercase() in descriptionValueAttributes }
-                .firstNotNullOfOrNull {
-                    val value = it.second
-                    return (value as? String)
-                }
+                .firstNotNullOfOrNull { (_, value) -> (value as? String)?.takeIf { it.isNotEmpty() } }
         } else {
             null
         }

kotlinx-schema-generator-core/src/jvmMain/kotlin/kotlinx/schema/generator/reflect/ReflectionUtils.kt

@@ -8,6 +8,7 @@ import kotlin.reflect.KProperty
 import kotlin.reflect.KProperty1
 import kotlin.reflect.KType
 import kotlin.reflect.KVisibility
+import kotlin.reflect.full.IllegalCallableAccessException
 import kotlin.reflect.full.allSuperclasses
 import kotlin.reflect.full.primaryConstructor
 import kotlin.reflect.jvm.javaMethod
@@ -16,13 +17,14 @@ import kotlin.reflect.jvm.kotlinFunction
 /**
  * Gets the [KType.classifier], ensuring it is a [KClass].
  */
-internal val KType.klass: KClass<*> get() {
-    return requireNotNull(classifier as? KClass<*>) {
-        "Unsupported classifier: $classifier. " +
-            "Only KClass classifiers are supported. Type parameters and other classifiers " +
-            "cannot be introspected using reflection."
+internal val KType.klass: KClass<*>
+    get() {
+        return requireNotNull(classifier as? KClass<*>) {
+            "Unsupported classifier: $classifier. " +
+                "Only KClass classifiers are supported. Type parameters and other classifiers " +
+                "cannot be introspected using reflection."
+        }
     }
-}
 
 /**
  * Finds a property in a class by name.
@@ -53,12 +55,43 @@ internal fun extractDescription(annotations: List<Annotation>): String? =
                 annotation.annotationClass.members
                     .filterIsInstance<KProperty1<Annotation, *>>()
                     .forEach { property ->
-                        add(property.name to property.get(annotation))
+                        val value =
+                            try {
+                                property.get(annotation)
+                            } catch (_: IllegalCallableAccessException) {
+                                fallbackViaJavaReflection(annotation, property) ?: return@forEach
+                            } catch (_: IllegalAccessException) {
+                                fallbackViaJavaReflection(annotation, property) ?: return@forEach
+                            }
+                        add(property.name to value)
                     }
             }
         Introspections.getDescriptionFromAnnotation(annotationName, annotationArguments)
     }
 
+/**
+ * KProperty1.get() wraps java.lang.IllegalAccessException in
+ * kotlin.reflect.full.IllegalCallableAccessException when the annotation
+ * interface is non-public (e.g. package-private for Kotlin `internal`
+ * annotations from external modules). Fall back to Java reflection on
+ * the proxy class, which is always accessible.
+ * Returns null when the fallback itself fails; null is safe here because
+ * Java annotation elements cannot return null values.
+ */
+private fun fallbackViaJavaReflection(
+    annotation: Annotation,
+    property: KProperty1<Annotation, *>,
+): Any? =
+    try {
+        val javaMethod = annotation.javaClass.getDeclaredMethod(property.name)
+        javaMethod.isAccessible = true
+        javaMethod.invoke(annotation)
+    } catch (_: ReflectiveOperationException) {
+        null
+    } catch (_: SecurityException) {
+        null
+    }
+
 /**
  * Returns a new [TypeRef] with the specified nullable flag.
  */

kotlinx-schema-generator-core/src/jvmTest/java/kotlinx/schema/generator/reflect/testfixtures/PackagePrivateAnnotationFixtures.java

@@ -0,0 +1,43 @@
+package kotlinx.schema.generator.reflect.testfixtures;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Test fixtures for the package-private annotation reflection fallback in {@code extractDescription}.
+ *
+ * <p>The nested {@code LLMDescription} annotation has no {@code public} modifier — it is
+ * package-private. This simulates third-party Kotlin {@code internal} annotations (which compile
+ * to package-private interfaces) that are accessed from outside their package. From a different
+ * package, {@code KProperty1.get()} may throw {@link IllegalAccessException}; the fallback in
+ * {@code extractDescription} recovers by calling {@code getDeclaredMethod()} on the proxy class
+ * with {@code isAccessible = true}.
+ */
+public final class PackagePrivateAnnotationFixtures {
+
+    /**
+     * Package-private annotation with two elements: {@code value} (shorthand) and
+     * {@code description} (verbose). Matched by simple name "LLMDescription" via
+     * {@code Introspections}.
+     */
+    @Target({ElementType.METHOD, ElementType.TYPE})
+    @Retention(RetentionPolicy.RUNTIME)
+    @interface LLMDescription {
+        String value() default "";
+
+        String description() default "";
+    }
+
+    /** Holder with a method annotated with the package-private {@code @LLMDescription}. */
+    public static final class AnnotatedHolder {
+        @LLMDescription(description = "product search tool")
+        public static void searchProducts() {}
+
+        @LLMDescription("find user by id")
+        public static void findUser() {}
+    }
+
+    private PackagePrivateAnnotationFixtures() {}
+}

kotlinx-schema-generator-core/src/jvmTest/kotlin/kotlinx/schema/generator/core/ir/IntrospectionsTest.kt

@@ -1,17 +1,20 @@
 package kotlinx.schema.generator.core.ir
 
 import io.kotest.matchers.shouldBe
+import io.kotest.matchers.shouldNotBe
+import org.junit.jupiter.api.Test
 import org.junit.jupiter.params.ParameterizedTest
 import org.junit.jupiter.params.provider.CsvSource
 
 class IntrospectionsTest {
+    //region Single-element annotation
     @ParameterizedTest
     @CsvSource(
         "Description, value",
         "LLMDescription, value",
         "P, description",
     )
-    fun getDescriptionFromAnnotation(
+    fun `extracts description from single-element annotation`(
         name: String,
         attribute: String,
     ) {
@@ -20,4 +23,31 @@ class IntrospectionsTest {
             listOf(attribute to "My Description"),
         ) shouldBe "My Description"
     }
+    //endregion
+
+    //region Multi-element LLMDescription regression
+    @Test
+    fun `extracts description from LLMDescription with description= style when value is empty`() {
+        // Regression: @LLMDescription has both value and description fields;
+        // when used as @LLMDescription(description = "text"), value defaults to ""
+        // and should not shadow the non-empty description field.
+        val result =
+            Introspections.getDescriptionFromAnnotation(
+                annotationName = "LLMDescription",
+                annotationArguments = listOf("value" to "", "description" to "Product identifier"),
+            )
+        result shouldBe "Product identifier"
+    }
+
+    @Test
+    fun `extracts description from LLMDescription with value= shorthand style`() {
+        // @LLMDescription("Product name") sets value="Product name", description=""
+        val result =
+            Introspections.getDescriptionFromAnnotation(
+                annotationName = "LLMDescription",
+                annotationArguments = listOf("value" to "Product name", "description" to ""),
+            )
+        result shouldBe "Product name"
+    }
+    //endregion
 }

kotlinx-schema-generator-core/src/jvmTest/kotlin/kotlinx/schema/generator/reflect/ExtractDescriptionTest.kt

@@ -0,0 +1,35 @@
+package kotlinx.schema.generator.reflect
+
+import io.kotest.matchers.shouldBe
+import kotlinx.schema.generator.reflect.testfixtures.PackagePrivateAnnotationFixtures
+import kotlin.test.Test
+
+class ExtractDescriptionTest {
+    //region Package-private annotation fallback
+    /**
+     * [PackagePrivateAnnotationFixtures.LLMDescription] is package-private in
+     * `kotlinx.schema.generator.reflect.testfixtures`. When [extractDescription] (in
+     * `kotlinx.schema.generator.reflect`) calls `KProperty1.get()` on its elements, the JVM
+     * denies access across packages for a non-public interface and throws
+     * [IllegalAccessException]. The fallback recovers via `getDeclaredMethod()` on the proxy
+     * class with `isAccessible = true`.
+     */
+    @Test
+    fun `extracts description from package-private annotation description= style via Java reflection fallback`() {
+        val method =
+            PackagePrivateAnnotationFixtures.AnnotatedHolder::class.java
+                .getDeclaredMethod("searchProducts")
+
+        extractDescription(method.annotations.toList()) shouldBe "product search tool"
+    }
+
+    @Test
+    fun `extracts description from package-private annotation value= shorthand style via Java reflection fallback`() {
+        val method =
+            PackagePrivateAnnotationFixtures.AnnotatedHolder::class.java
+                .getDeclaredMethod("findUser")
+
+        extractDescription(method.annotations.toList()) shouldBe "find user by id"
+    }
+    //endregion
+}

kotlinx-schema-generator-json/src/jvmTest/kotlin/kotlinx/schema/generator/json/FunctionCallingSchemaGeneratorTest.kt

@@ -11,6 +11,19 @@ import kotlinx.serialization.json.Json
 import kotlin.reflect.KCallable
 import kotlin.test.Test
 
+/**
+ * Local test annotation mirroring the shape of [ai.koog.agents.core.tools.annotations.LLMDescription]:
+ * two String elements — [value] (shorthand) and [description] (verbose).
+ *
+ * Matched by simple name "LLMDescription" via [kotlinx.schema.generator.core.ir.Introspections].
+ */
+@Target(AnnotationTarget.FUNCTION, AnnotationTarget.VALUE_PARAMETER, AnnotationTarget.CLASS)
+@Retention(AnnotationRetention.RUNTIME)
+internal annotation class LLMDescription(
+    val value: String = "",
+    val description: String = "",
+)
+
 class FunctionCallingSchemaGeneratorTest {
     private val generator =
         ReflectionFunctionCallingSchemaGenerator(
@@ -677,4 +690,52 @@ class FunctionCallingSchemaGeneratorTest {
             }
             """.trimIndent()
     }
+
+    //region LLMDescription regression tests
+    object LLMDescriptionTool {
+        // Regression: @LLMDescription has two elements (value, description).
+        // Using the verbose description= style leaves value="" — the extractor must not return ""
+        // and instead find the non-empty description field.
+        @LLMDescription(description = "Search for products in the catalog")
+        fun search(
+            @LLMDescription(description = "Search query string")
+            query: String,
+            @LLMDescription("Maximum number of results")
+            limit: Int = 10,
+        ): String = ""
+    }
+
+    @Test
+    fun `extracts descriptions from LLMDescription verbose style on function and parameters`() {
+        // Regression: @LLMDescription(description = "text") must not produce empty description.
+        // Previously getDescriptionFromAnnotation returned "" because value="" was the first match.
+        val schemaString = generator.generateSchemaString(LLMDescriptionTool::search)
+
+        schemaString shouldEqualJson
+            // language=json
+            """
+            {
+                "type": "function",
+                "name": "search",
+                "description": "Search for products in the catalog",
+                "strict": true,
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "query": {
+                            "type": "string",
+                            "description": "Search query string"
+                        },
+                        "limit": {
+                            "type": "integer",
+                            "description": "Maximum number of results"
+                        }
+                    },
+                    "required": ["query", "limit"],
+                    "additionalProperties": false
+                }
+            }
+            """.trimIndent()
+    }
+    //endregion
 }