Provide @UnstableMetadataApi and mark kotlin_module related API with it,

as it is not finished yet.

libraries/kotlinx-metadata/jvm/api/kotlinx-metadata-jvm.api

@@ -1391,3 +1391,6 @@ public final class kotlinx/metadata/jvm/KotlinModuleMetadata$Writer : kotlinx/me
 	public static synthetic fun write$default (Lkotlinx/metadata/jvm/KotlinModuleMetadata$Writer;[IILjava/lang/Object;)Lkotlinx/metadata/jvm/KotlinModuleMetadata;
 }
 
+public abstract interface annotation class kotlinx/metadata/jvm/UnstableMetadataApi : java/lang/annotation/Annotation {
+}
+

libraries/kotlinx-metadata/jvm/src/kotlinx/metadata/jvm/KotlinModuleMetadata.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright 2010-2018 JetBrains s.r.o. and Kotlin Programming Language contributors.
+ * Copyright 2010-2023 JetBrains s.r.o. and Kotlin Programming Language contributors.
  * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
  */
 
@@ -25,6 +25,7 @@ import org.jetbrains.kotlin.metadata.jvm.deserialization.serializeToByteArray
  *
  * @property bytes the byte array representing the contents of a `.kotlin_module` file
  */
+@UnstableMetadataApi
 class KotlinModuleMetadata(@Suppress("MemberVisibilityCanBePrivate") val bytes: ByteArray) {
     @get:IgnoreInApiDump
     internal val data: ModuleMapping = ModuleMapping.loadModuleMapping(
@@ -126,6 +127,7 @@ class KotlinModuleMetadata(@Suppress("MemberVisibilityCanBePrivate") val bytes:
          * which means that it's either not the content of a .kotlin_module file, or it has been corrupted.
          */
         @JvmStatic
+        @UnstableMetadataApi
         fun read(bytes: ByteArray): KotlinModuleMetadata? {
             try {
                 val result = KotlinModuleMetadata(bytes)
@@ -149,6 +151,7 @@ class KotlinModuleMetadata(@Suppress("MemberVisibilityCanBePrivate") val bytes:
          * @param metadataVersion metadata version to be written to the metadata (see [Metadata.metadataVersion]),
          *   [KotlinClassMetadata.COMPATIBLE_METADATA_VERSION] by default
          */
+        @UnstableMetadataApi
         fun write(kmModule: KmModule, metadataVersion: IntArray = COMPATIBLE_METADATA_VERSION): KotlinModuleMetadata =
             Writer().also { kmModule.accept(it) }.write(metadataVersion)
     }
@@ -160,6 +163,7 @@ class KotlinModuleMetadata(@Suppress("MemberVisibilityCanBePrivate") val bytes:
  * When using this class, [visitEnd] must be called exactly once and after calls to all other visit* methods.
  */
 @Deprecated(VISITOR_API_MESSAGE)
+@UnstableMetadataApi
 abstract class KmModuleVisitor(private val delegate: KmModuleVisitor? = null) {
     /**
      * Visits the table of all single- and multi-file facades declared in some package of this module.
@@ -208,6 +212,7 @@ abstract class KmModuleVisitor(private val delegate: KmModuleVisitor? = null) {
 /**
  * Represents a Kotlin JVM module file.
  */
+@UnstableMetadataApi
 class KmModule : KmModuleVisitor() {
     /**
      * Table of all single- and multi-file facades declared in some package of this module, where keys are '.'-separated package names.
@@ -267,6 +272,7 @@ class KmModule : KmModuleVisitor() {
  * @property multiFileClassParts the map of multi-file classes where keys are names of multi-file class parts,
  *   and values are names of the corresponding multi-file facades
  */
+@UnstableMetadataApi
 class KmPackageParts(
     val fileFacades: MutableList<String>,
     val multiFileClassParts: MutableMap<String, String>

libraries/kotlinx-metadata/jvm/src/kotlinx/metadata/jvm/UnstableMetadataApi.kt

@@ -0,0 +1,17 @@
+/*
+ * Copyright 2010-2023 JetBrains s.r.o. and Kotlin Programming Language contributors.
+ * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
+ */
+
+package kotlinx.metadata.jvm
+
+/**
+ * Annotation marks an API that is still in development and not feature-complete or finalized.
+ * Such an API does not provide compatibility guarantees.
+ * It can be changed in future releases without migration aids or removed without replacement.
+ */
+@RequiresOptIn(
+    "This part of API is not yet finished, does not provide compatibility guarantees and can be changed in the future without notice",
+    level = RequiresOptIn.Level.WARNING
+)
+annotation class UnstableMetadataApi

libraries/kotlinx-metadata/jvm/test/kotlinx/metadata/test/MetadataSmokeTest.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright 2000-2018 JetBrains s.r.o. and Kotlin Programming Language contributors.
+ * Copyright 2010-2023 JetBrains s.r.o. and Kotlin Programming Language contributors.
  * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
  */
 
@@ -191,6 +191,7 @@ class MetadataSmokeTest {
     }
 
     @Test
+    @OptIn(UnstableMetadataApi::class)
     fun metadataVersionEarlierThan1_4() {
         val dummy = (KotlinClassMetadata.read(MetadataSmokeTest::class.java.readMetadata()) as KotlinClassMetadata.Class).toKmClass()
         val mv = intArrayOf(1, 3)

libraries/tools/kotlinp/src/org/jetbrains/kotlin/kotlinp/Kotlinp.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright 2000-2018 JetBrains s.r.o. and Kotlin Programming Language contributors.
+ * Copyright 2010-2023 JetBrains s.r.o. and Kotlin Programming Language contributors.
  * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
  */
 
@@ -8,6 +8,7 @@ package org.jetbrains.kotlin.kotlinp
 import kotlinx.metadata.InconsistentKotlinMetadataException
 import kotlinx.metadata.jvm.KotlinClassMetadata
 import kotlinx.metadata.jvm.KotlinModuleMetadata
+import kotlinx.metadata.jvm.UnstableMetadataApi
 import java.io.File
 
 class Kotlinp(private val settings: KotlinpSettings) {
@@ -34,10 +35,12 @@ class Kotlinp(private val settings: KotlinpSettings) {
         }
     }
 
+    @OptIn(UnstableMetadataApi::class)
     internal fun renderModuleFile(metadata: KotlinModuleMetadata?): String =
         if (metadata != null) ModuleFilePrinter(settings).print(metadata)
         else buildString { appendLine("unsupported file") }
 
+    @OptIn(UnstableMetadataApi::class)
     internal fun readModuleFile(file: File): KotlinModuleMetadata? =
         KotlinModuleMetadata.read(file.readBytes())
 }

libraries/tools/kotlinp/src/org/jetbrains/kotlin/kotlinp/Main.kt

@@ -1,10 +1,11 @@
 /*
- * Copyright 2000-2018 JetBrains s.r.o. and Kotlin Programming Language contributors.
+ * Copyright 2010-2023 JetBrains s.r.o. and Kotlin Programming Language contributors.
  * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
  */
 
 package org.jetbrains.kotlin.kotlinp
 
+import kotlinx.metadata.jvm.UnstableMetadataApi
 import java.io.File
 import java.io.IOException
 import kotlin.system.exitProcess
@@ -40,7 +41,7 @@ object Main {
             val text = try {
                 when (file.extension) {
                     "class" -> kotlinp.renderClassFile(kotlinp.readClassFile(file))
-                    "kotlin_module" -> kotlinp.renderModuleFile(kotlinp.readModuleFile(file))
+                    "kotlin_module" -> @OptIn(UnstableMetadataApi::class) kotlinp.renderModuleFile(kotlinp.readModuleFile(file))
                     else -> throw KotlinpException("only .class and .kotlin_module files are supported")
                 }
             } catch (e: IOException) {

libraries/tools/kotlinp/src/org/jetbrains/kotlin/kotlinp/printers.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright 2000-2018 JetBrains s.r.o. and Kotlin Programming Language contributors.
+ * Copyright 2010-2023 JetBrains s.r.o. and Kotlin Programming Language contributors.
  * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
  */
 
@@ -685,6 +685,7 @@ class ModuleFilePrinter(private val settings: KotlinpSettings) {
         sb.appendLine("}")
     }
 
+    @UnstableMetadataApi
     fun print(metadata: KotlinModuleMetadata): String {
         val kmModule = metadata.toKmModule()
         kmModule.packageParts.forEach { (fqName, kmPackageParts) ->

libraries/tools/kotlinp/test/org/jetbrains/kotlin/kotlinp/test/KotlinpTestUtils.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright 2010-2018 JetBrains s.r.o. and Kotlin Programming Language contributors.
+ * Copyright 2010-2023 JetBrains s.r.o. and Kotlin Programming Language contributors.
  * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
  */
 
@@ -9,6 +9,7 @@ import com.intellij.openapi.Disposable
 import junit.framework.TestCase.assertEquals
 import kotlinx.metadata.jvm.KotlinClassMetadata
 import kotlinx.metadata.jvm.KotlinModuleMetadata
+import kotlinx.metadata.jvm.UnstableMetadataApi
 import org.jetbrains.kotlin.checkers.setupLanguageVersionSettingsForCompilerTests
 import org.jetbrains.kotlin.cli.jvm.compiler.EnvironmentConfigFiles
 import org.jetbrains.kotlin.cli.jvm.compiler.KotlinCoreEnvironment
@@ -32,6 +33,7 @@ fun compileAndPrintAllFiles(file: File, disposable: Disposable, tmpdir: File, co
 
     val kotlinp = Kotlinp(KotlinpSettings(isVerbose = true))
 
+    @OptIn(UnstableMetadataApi::class)
     compile(file, disposable, tmpdir) { outputFile ->
         when (outputFile.extension) {
             "kotlin_module" -> {
@@ -130,8 +132,10 @@ private fun transformClassFileWithNodes(classFile: KotlinClassMetadata): KotlinC
     }
 
 @Suppress("DEPRECATION") // We're testing that reading/writing with KmNodes is identical to direct
+@OptIn(UnstableMetadataApi::class)
 private fun transformModuleFileWithReadWriteVisitors(moduleFile: KotlinModuleMetadata): KotlinModuleMetadata =
     KotlinModuleMetadata.Writer().apply(moduleFile::accept).write()
 
+@OptIn(UnstableMetadataApi::class)
 private fun transformModuleFileWithNodes(moduleFile: KotlinModuleMetadata): KotlinModuleMetadata =
     KotlinModuleMetadata.write(moduleFile.toKmModule())