feat: JSpecify support (#5365)

Author: danil-pavlov

docs/topics/jvm/java-interop.md

@@ -199,22 +199,32 @@ Kotlin types. The compiler supports several flavors of nullability annotations,
 
   * [JetBrains](https://www.jetbrains.com/idea/help/nullable-and-notnull-annotations.html)
 (`@Nullable` and `@NotNull` from the `org.jetbrains.annotations` package)
-  * [JSpecify](https://jspecify.dev/) (`org.jspecify.annotations`)
+  * [JSpecify](#jspecify-support) (`org.jspecify.annotations`)
   * Android (`com.android.annotations` and `android.support.annotations`)
-  * JSR-305 (`javax.annotation`, more details below)
+  * [JSR-305](#jsr-305-support) (`javax.annotation`)
   * FindBugs (`edu.umd.cs.findbugs.annotations`)
   * Eclipse (`org.eclipse.jdt.annotation`)
-  * Lombok (`lombok.NonNull`)
+  * [Lombok](lombok.md) (`lombok.NonNull`)
   * RxJava 3 (`io.reactivex.rxjava3.annotations`)
 
-You can specify whether the compiler reports a nullability mismatch based on the information from specific types of 
-nullability annotations. Use the compiler option `-Xnullability-annotations=@<package-name>:<report-level>`. 
-In the argument, specify the fully qualified nullability annotations package and one of these report levels:
+You can instruct the compiler to report nullability mismatches for specific nullability annotations with the following compiler option:
+
+```bash
+-Xnullability-annotations=@<package-name>:<report-level>
+``` 
+
+Specify the package name for the fully qualified nullability annotations and one of these report levels:
+
 * `ignore` to ignore nullability mismatches
 * `warn` to report warnings
 * `strict` to report errors.
 
-See the full list of supported nullability annotations in the 
+> [JSpecify](#jspecify-support) is the only supported flavor that uses `strict` report level by default.
+> Use it to report errors on nullability annotations without additional configuration.
+>
+{style="note"}
+
+See the full list of supported nullability annotations in the
 [Kotlin compiler source code](https://github.com/JetBrains/kotlin/blob/master/core/compiler.common.jvm/src/org/jetbrains/kotlin/load/java/JvmAnnotationNames.kt).
 
 ### Annotating type arguments and type parameters
@@ -312,6 +322,66 @@ nullability annotations support the `TYPE_USE` target (`org.jetbrains.annotation
 >
 {style="note"}
 
+### JSpecify support
+
+Kotlin supports the [JSpecify](https://jspecify.dev/) nullability annotations, which provide a unified set of annotations
+for Java nullability. JSpecify allows you to provide detailed nullability information for Java declarations,
+helping Kotlin maintain null-safety when working with Java code.
+
+Kotlin supports the following annotations in the `org.jspecify.annotations` package:
+
+* `@Nullable` marks a type as nullable.
+* `@NonNull` marks a type as non-nullable.
+* `@NullMarked` marks all types within a scope, for example a class or package, as non-nullable by default unless annotated
+  otherwise.
+
+  This annotation doesn't apply to local variables and [type variables (generics)](https://jspecify.dev/docs/user-guide/#using-type-variables-in-generic-types).
+  Type variables remain "null-agnostic" until a specific nullable or non-nullable type is provided.
+
+* `@NullUnmarked` reverses the effect of `@NullMarked`, making all types within the scope as [platform types](#null-safety-and-platform-types).
+
+Consider the following Java class with JSpecify annotations:
+ 
+```java
+// Java
+import org.jspecify.annotations.*;
+
+@NullMarked
+public class InventoryService {
+    public String notNull() { return ""; }
+    public @Nullable String nullable() { return null; }
+}
+```
+ 
+In Kotlin, these are treated as regular nullable and non-nullable types rather than [platform types](#null-safety-and-platform-types):
+ 
+```kotlin
+// Kotlin
+fun test(inventory: InventoryService) {
+   inventory.notNull().length // OK
+   inventory.nullable().length // Error: only safe (?.) or non-null asserted (!!) calls are allowed
+}
+```
+
+By default, the Kotlin compiler reports nullability mismatches for JSpecify annotations as errors.
+You can customize the severity of JSpecify nullability diagnostics using the following compiler option:
+
+```bash
+-Xjspecify-annotations=<report-level>
+```
+
+Available report levels are:
+
+| Level    | Description                                          |
+|----------|------------------------------------------------------|
+| `strict` | Reports errors for nullability mismatches (default). |
+| `warn`   | Reports warnings.                                    |
+| `ignore` | Ignores nullability mismatches.                      |
+
+> For more information on JSpecify annotations, see the [JSpecify user guide](https://jspecify.dev/docs/user-guide).
+> 
+{type="tip"}
+
 ### JSR-305 support
 
 The [`@Nonnull`](https://www.javadoc.io/doc/com.google.code.findbugs/jsr305/latest/javax/annotation/Nonnull.html) annotation defined