Get rid of @Suppress("INVISIBLE_REFERENCE") for usage of internal declarations (#2444)

* Introduce additional internal opt-in annotation to hide declarations even more

* Rename JsonWriter and SerialReader to something more internal-ish

* Refactor internal extensions on Json into top-level functions to remove them from completion (because even optable-in declarations are shown in completion for all users)

* Propagate opt-ins to verifyKotlinModule task

Related: https://youtrack.jetbrains.com/issue/KTIJ-27132

Author: sandwwraith

buildSrc/src/main/kotlin/Java9Modularity.kt

@@ -131,6 +131,7 @@ object Java9Modularity {
                 // To support LV override when set in aggregate builds
                 languageVersion = compileTask.kotlinOptions.languageVersion
                 freeCompilerArgs += listOf("-Xjdk-release=9",  "-Xsuppress-version-warnings")
+                options.optIn.addAll(compileTask.kotlinOptions.options.optIn)
             }
             // work-around for https://youtrack.jetbrains.com/issue/KT-60583
             inputs.files(

core/commonMain/src/kotlinx/serialization/internal/ElementMarker.kt

@@ -4,13 +4,13 @@
 
 package kotlinx.serialization.internal
 
-import kotlinx.serialization.ExperimentalSerializationApi
+import kotlinx.serialization.*
 import kotlinx.serialization.descriptors.SerialDescriptor
 import kotlinx.serialization.encoding.CompositeDecoder
 
 @OptIn(ExperimentalSerializationApi::class)
-@PublishedApi
-internal class ElementMarker(
+@CoreFriendModuleApi
+public class ElementMarker(
     private val descriptor: SerialDescriptor,
     // Instead of inheritance and virtual function in order to keep cross-module internal modifier via suppresses
     // Can be reworked via public + internal api if necessary
@@ -45,15 +45,15 @@ internal class ElementMarker(
         }
     }
 
-    fun mark(index: Int) {
+    public fun mark(index: Int) {
         if (index < Long.SIZE_BITS) {
             lowerMarks = lowerMarks or (1L shl index)
         } else {
             markHigh(index)
         }
     }
 
-    fun nextUnmarkedIndex(): Int {
+    public fun nextUnmarkedIndex(): Int {
         val elementsCount = descriptor.elementsCount
         while (lowerMarks != -1L) {
             val index = lowerMarks.inv().countTrailingZeroBits()

core/commonMain/src/kotlinx/serialization/internal/JsonInternalDependencies.kt

@@ -1,14 +1,14 @@
 package kotlinx.serialization.internal
 
-import kotlinx.serialization.*
 import kotlinx.serialization.descriptors.*
 
 /*
- * Methods that are required for kotlinx-serialization-json, but are not effectively public
- * and actually represent our own technical debt.
- * This methods are not intended for public use
+ * Methods that are required for kotlinx-serialization-json, but are not effectively public.
+ *
+ * Anything marker with this annotation is not intended for public use.
  */
+@RequiresOptIn(level = RequiresOptIn.Level.ERROR)
+internal annotation class CoreFriendModuleApi
 
-@InternalSerializationApi
-@Deprecated(message = "Should not be used", level = DeprecationLevel.ERROR)
+@CoreFriendModuleApi
 public fun SerialDescriptor.jsonCachedSerialNames(): Set<String> = cachedSerialNames()

core/commonTest/src/kotlinx/serialization/ElementMarkerTest.kt

@@ -2,10 +2,11 @@ package kotlinx.serialization
 
 import kotlinx.serialization.descriptors.*
 import kotlinx.serialization.encoding.CompositeDecoder
-import kotlinx.serialization.internal.ElementMarker
+import kotlinx.serialization.internal.*
 import kotlin.test.Test
 import kotlin.test.assertEquals
 
+@OptIn(CoreFriendModuleApi::class)
 class ElementMarkerTest {
     @Test
     fun testNothingWasRead() {

formats/json-okio/build.gradle.kts

@@ -15,6 +15,12 @@ apply(from = rootProject.file("gradle/configure-source-sets.gradle"))
 
 kotlin {
     sourceSets {
+        configureEach {
+            languageSettings {
+                optIn("kotlinx.serialization.internal.CoreFriendModuleApi")
+                optIn("kotlinx.serialization.json.internal.JsonFriendModuleApi")
+            }
+        }
         val commonMain by getting {
             dependencies {
                 api(project(":kotlinx-serialization-core"))
@@ -58,4 +64,4 @@ if (isNewWasmTargetEnabled) {
             }
         }
     }
-}
+}

formats/json-okio/commonMain/src/kotlinx/serialization/json/okio/OkioStreams.kt

@@ -2,8 +2,6 @@
  * Copyright 2017-2022 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
  */
 
-@file:Suppress("INVISIBLE_REFERENCE", "INVISIBLE_MEMBER")
-
 package kotlinx.serialization.json.okio
 
 import kotlinx.serialization.*
@@ -29,7 +27,7 @@ public fun <T> Json.encodeToBufferedSink(
 ) {
     val writer = JsonToOkioStreamWriter(sink)
     try {
-        encodeByWriter(writer, serializer, value)
+        encodeByWriter(this, writer, serializer, value)
     } finally {
         writer.release()
     }
@@ -62,7 +60,7 @@ public fun <T> Json.decodeFromBufferedSource(
     deserializer: DeserializationStrategy<T>,
     source: BufferedSource
 ): T {
-    return decodeByReader(deserializer, OkioSerialReader(source))
+    return decodeByReader(this, deserializer, OkioSerialReader(source))
 }
 
 /**
@@ -101,7 +99,7 @@ public fun <T> Json.decodeBufferedSourceToSequence(
     deserializer: DeserializationStrategy<T>,
     format: DecodeSequenceMode = DecodeSequenceMode.AUTO_DETECT
 ): Sequence<T> {
-    return decodeToSequenceByReader(OkioSerialReader(source), deserializer, format)
+    return decodeToSequenceByReader(this, OkioSerialReader(source), deserializer, format)
 }
 
 /**

formats/json-okio/commonMain/src/kotlinx/serialization/json/okio/internal/OkioJsonStreams.kt

@@ -2,16 +2,39 @@
  * Copyright 2017-2022 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
  */
 
-@file:Suppress("INVISIBLE_REFERENCE", "INVISIBLE_MEMBER", "CANNOT_OVERRIDE_INVISIBLE_MEMBER")
-
 package kotlinx.serialization.json.okio.internal
 
-import kotlinx.serialization.json.internal.ESCAPE_STRINGS
-import kotlinx.serialization.json.internal.JsonWriter
-import kotlinx.serialization.json.internal.SerialReader
+import kotlinx.serialization.json.internal.*
 import okio.*
 
-internal class JsonToOkioStreamWriter(private val sink: BufferedSink) : JsonWriter {
+// Copied from kotlinx/serialization/json/internal/StringOps.kt
+private fun toHexChar(i: Int) : Char {
+    val d = i and 0xf
+    return if (d < 10) (d + '0'.code).toChar()
+    else (d - 10 + 'a'.code).toChar()
+}
+
+// Copied from kotlinx/serialization/json/internal/StringOps.kt
+private val ESCAPE_STRINGS: Array<String?> = arrayOfNulls<String>(93).apply {
+    for (c in 0..0x1f) {
+        val c1 = toHexChar(c shr 12)
+        val c2 = toHexChar(c shr 8)
+        val c3 = toHexChar(c shr 4)
+        val c4 = toHexChar(c)
+        this[c] = "\\u$c1$c2$c3$c4"
+    }
+    this['"'.code] = "\\\""
+    this['\\'.code] = "\\\\"
+    this['\t'.code] = "\\t"
+    this['\b'.code] = "\\b"
+    this['\n'.code] = "\\n"
+    this['\r'.code] = "\\r"
+    this[0x0c] = "\\f"
+}
+
+
+
+internal class JsonToOkioStreamWriter(private val sink: BufferedSink) : InternalJsonWriter {
     override fun writeLong(value: Long) {
         write(value.toString())
     }
@@ -54,7 +77,7 @@ private const val HIGH_SURROGATE_HEADER = 0xd800 - (0x010000 ushr 10)
 private const val LOW_SURROGATE_HEADER = 0xdc00
 
 
-internal class OkioSerialReader(private val source: BufferedSource): SerialReader {
+internal class OkioSerialReader(private val source: BufferedSource): InternalJsonReader {
     /*
     A sequence of code points is read from UTF-8, some of it can take 2 characters.
     In case the last code point requires 2 characters, and the array is already full, we buffer the second character

formats/json-tests/build.gradle.kts

@@ -25,6 +25,12 @@ tasks.named("koverVerify") {
 
 kotlin {
     sourceSets {
+        configureEach {
+            languageSettings {
+                optIn("kotlinx.serialization.internal.CoreFriendModuleApi")
+                optIn("kotlinx.serialization.json.internal.JsonFriendModuleApi")
+            }
+        }
         val commonTest by getting {
             dependencies {
                 api(project(":kotlinx-serialization-json"))
@@ -64,4 +70,4 @@ if (!isNewWasmTargetEnabled) {
     tasks.named("wasmD8Test", KotlinJsTest::class) {
         filter.excludePatterns += "kotlinx.serialization.features.EmojiTest"
     }
-}
+}

formats/json-tests/commonTest/src/kotlinx/serialization/json/JsonTestBase.kt

@@ -49,7 +49,7 @@ abstract class JsonTestBase {
                 encodeViaStream(serializer, value)
             }
             JsonTestingMode.TREE -> {
-                val tree = writeJson(value, serializer)
+                val tree = writeJson(this, value, serializer)
                 encodeToString(tree)
             }
             JsonTestingMode.OKIO_STREAMS -> {
@@ -77,8 +77,8 @@ abstract class JsonTestBase {
                 decodeViaStream(deserializer, source)
             }
             JsonTestingMode.TREE -> {
-                val tree = decodeStringToJsonTree(deserializer, source)
-                readJson(tree, deserializer)
+                val tree = decodeStringToJsonTree(this, deserializer, source)
+                readJson(this, tree, deserializer)
             }
             JsonTestingMode.OKIO_STREAMS -> {
                 val buffer = Buffer()

formats/json/api/kotlinx-serialization-json.api

@@ -383,33 +383,29 @@ public final class kotlinx/serialization/json/JvmStreamsKt {
 	public static final fun encodeToStream (Lkotlinx/serialization/json/Json;Lkotlinx/serialization/SerializationStrategy;Ljava/lang/Object;Ljava/io/OutputStream;)V
 }
 
-public final class kotlinx/serialization/json/internal/JsonStreamsKt {
-	public static final fun decodeByReader (Lkotlinx/serialization/json/Json;Lkotlinx/serialization/DeserializationStrategy;Lkotlinx/serialization/json/internal/SerialReader;)Ljava/lang/Object;
-	public static final fun decodeToSequenceByReader (Lkotlinx/serialization/json/Json;Lkotlinx/serialization/json/internal/SerialReader;Lkotlinx/serialization/DeserializationStrategy;Lkotlinx/serialization/json/DecodeSequenceMode;)Lkotlin/sequences/Sequence;
-	public static synthetic fun decodeToSequenceByReader$default (Lkotlinx/serialization/json/Json;Lkotlinx/serialization/json/internal/SerialReader;Lkotlinx/serialization/DeserializationStrategy;Lkotlinx/serialization/json/DecodeSequenceMode;ILjava/lang/Object;)Lkotlin/sequences/Sequence;
-	public static final fun encodeByWriter (Lkotlinx/serialization/json/Json;Lkotlinx/serialization/json/internal/JsonWriter;Lkotlinx/serialization/SerializationStrategy;Ljava/lang/Object;)V
+public abstract interface class kotlinx/serialization/json/internal/InternalJsonReader {
+	public abstract fun read ([CII)I
 }
 
-public abstract interface class kotlinx/serialization/json/internal/JsonWriter {
+public abstract interface class kotlinx/serialization/json/internal/InternalJsonWriter {
 	public abstract fun release ()V
 	public abstract fun write (Ljava/lang/String;)V
 	public abstract fun writeChar (C)V
 	public abstract fun writeLong (J)V
 	public abstract fun writeQuoted (Ljava/lang/String;)V
 }
 
-public abstract interface class kotlinx/serialization/json/internal/SerialReader {
-	public abstract fun read ([CII)I
+public final class kotlinx/serialization/json/internal/JsonStreamsKt {
+	public static final fun decodeByReader (Lkotlinx/serialization/json/Json;Lkotlinx/serialization/DeserializationStrategy;Lkotlinx/serialization/json/internal/InternalJsonReader;)Ljava/lang/Object;
+	public static final fun decodeToSequenceByReader (Lkotlinx/serialization/json/Json;Lkotlinx/serialization/json/internal/InternalJsonReader;Lkotlinx/serialization/DeserializationStrategy;Lkotlinx/serialization/json/DecodeSequenceMode;)Lkotlin/sequences/Sequence;
+	public static synthetic fun decodeToSequenceByReader$default (Lkotlinx/serialization/json/Json;Lkotlinx/serialization/json/internal/InternalJsonReader;Lkotlinx/serialization/DeserializationStrategy;Lkotlinx/serialization/json/DecodeSequenceMode;ILjava/lang/Object;)Lkotlin/sequences/Sequence;
+	public static final fun encodeByWriter (Lkotlinx/serialization/json/Json;Lkotlinx/serialization/json/internal/InternalJsonWriter;Lkotlinx/serialization/SerializationStrategy;Ljava/lang/Object;)V
 }
 
 public final class kotlinx/serialization/json/internal/StreamingJsonDecoderKt {
 	public static final fun decodeStringToJsonTree (Lkotlinx/serialization/json/Json;Lkotlinx/serialization/DeserializationStrategy;Ljava/lang/String;)Lkotlinx/serialization/json/JsonElement;
 }
 
-public final class kotlinx/serialization/json/internal/StringOpsKt {
-	public static final fun getESCAPE_STRINGS ()[Ljava/lang/String;
-}
-
 public final class kotlinx/serialization/json/internal/TreeJsonDecoderKt {
 	public static final fun readJson (Lkotlinx/serialization/json/Json;Lkotlinx/serialization/json/JsonElement;Lkotlinx/serialization/DeserializationStrategy;)Ljava/lang/Object;
 }