[KLIB tool] Introduce a '-test-mode' CLI option

This is an option that allows running the commands that support it
in a special "test mode". The "test mode" means (but not limited to)
that a command may, for example, sort the output which is unsorted
by default, and this way guarantee stable output. This is essentially
helpful for tests, which rely on the command output.

^KT-62340

kotlin-native/klib/src/main/kotlin/org/jetbrains/kotlin/cli/klib/KlibToolArguments.kt

@@ -13,4 +13,5 @@ internal class KlibToolArguments(
         val repository: String?,
         val printSignatures: Boolean,
         val signatureVersion: KotlinIrSignatureVersion?,
+        val testMode: Boolean,
 )

kotlin-native/klib/src/main/kotlin/org/jetbrains/kotlin/cli/klib/KlibToolArgumentsParser.kt

@@ -41,6 +41,7 @@ internal class KlibToolArgumentsParser {
                 repository = extraArgs[ExtraOption.REPOSITORY]?.last(),
                 printSignatures = extraArgs[ExtraOption.PRINT_SIGNATURES]?.last()?.toBoolean() == true,
                 signatureVersion,
+                testMode = extraArgs[ExtraOption.INTERNAL_TEST_MODE]?.last()?.toBoolean() == true
         )
     }
 
@@ -105,7 +106,17 @@ internal class KlibToolArgumentsParser {
 private enum class ExtraOption(val option: String) {
     REPOSITORY("-repository"),
     PRINT_SIGNATURES("-print-signatures"),
-    SIGNATURE_VERSION("-signature-version");
+    SIGNATURE_VERSION("-signature-version"),
+
+    /**
+     * This is an option that allows running the commands that support it in a special "test mode".
+     * The "test mode" means (but not limited to) that a command may, for example, sort the output
+     * which is unsorted by default, and this way guarantee stable output. This is essentially helpful
+     * for tests, which rely on the command output.
+     *
+     * NOTE: This option is not supposed to be advertised in KLIB tool's "usage info".
+     */
+    INTERNAL_TEST_MODE("-test-mode");
 
     companion object {
         fun parseOrNull(option: String): ExtraOption? = entries.firstOrNull { it.option == option }

kotlin-native/klib/src/main/kotlin/org/jetbrains/kotlin/cli/klib/KotlinpBasedMetadataDumper.kt

@@ -40,6 +40,12 @@ internal class KotlinpBasedMetadataDumper(
 
     private val printer = Printer(output)
 
+    /**
+     * @param testMode if `true` then a special pre-processing is performed towards the metadata before rendering:
+     *        - empty package fragments are removed
+     *        - package fragments with the same package FQN are merged
+     *        - classes are sorted in alphabetical order
+     */
     fun dumpLibrary(library: KotlinLibrary, testMode: Boolean) {
         val moduleMetadata = loadModuleMetadata(library)
                 .let { originalModuleMetadata -> if (testMode) preprocessMetadataForTests(originalModuleMetadata) else originalModuleMetadata }

kotlin-native/klib/src/main/kotlin/org/jetbrains/kotlin/cli/klib/main.kt

@@ -198,14 +198,8 @@ internal class KlibToolCommand(private val args: KlibToolArguments) {
         printer.print(module)
     }
 
-    /**
+    fun dumpMetadata(output: Appendable) {
-     * @param testMode if `true` then a special pre-processing is performed towards the metadata before rendering:
+        KotlinpBasedMetadataDumper(output, args.printSignatures, args.signatureVersion).dumpLibrary(libraryInCurrentDir(args.libraryNameOrPath), args.testMode)
-     *        - empty package fragments are removed
-     *        - package fragments with the same package FQN are merged
-     *        - classes are sorted in alphabetical order
-     */
-    fun dumpMetadata(output: Appendable, testMode: Boolean) {
-        KotlinpBasedMetadataDumper(output, args.printSignatures, args.signatureVersion).dumpLibrary(libraryInCurrentDir(args.libraryNameOrPath), testMode)
     }
 
     fun signatures(output: Appendable) {
@@ -258,7 +252,7 @@ fun main(rawArgs: Array<String>) {
         "dump-abi" -> command.dumpAbi(System.out)
         "dump-ir" -> command.dumpIr(System.out)
         "dump-ir-signatures" -> command.dumpIrSignatures(System.out)
-        "dump-metadata" -> command.dumpMetadata(System.out, testMode = false)
+        "dump-metadata" -> command.dumpMetadata(System.out)
         "dump-metadata-signatures" -> command.dumpMetadataSignatures(System.out)
         "contents" -> command.contents(System.out)
         "signatures" -> command.signatures(System.out)