Implement basic version of improved unused return value checker.

Checker supports most expressions, but without separation between stable and unstable values.

Add analysis and CLI flag with 3 modes to support further extension to FULL mode.

Add @MustUseReturnValue and @IgnorableReturnValue to stdlib.

#KT-74804 Fixed
#KT-74806 Fixed


Merge-request: KT-MR-19960
Merged-by: Leonid Startsev <[email protected]>

Author: sandwwraith

analysis/analysis-api-fir/src/org/jetbrains/kotlin/analysis/api/fir/diagnostics/KaFirDataClassConverters.kt

@@ -4569,6 +4569,12 @@ internal val KT_DIAGNOSTIC_CONVERTER = KaDiagnosticConverterBuilder.buildConvert
             token,
         )
     }
+    add(FirErrors.RETURN_VALUE_NOT_USED) { firDiagnostic ->
+        ReturnValueNotUsedImpl(
+            firDiagnostic as KtPsiDiagnostic,
+            token,
+        )
+    }
     add(FirErrors.UNSAFE_CALL) { firDiagnostic ->
         UnsafeCallImpl(
             firSymbolBuilder.typeBuilder.buildKtType(firDiagnostic.a),

analysis/analysis-api-fir/src/org/jetbrains/kotlin/analysis/api/fir/diagnostics/KaFirDiagnostics.kt

@@ -3189,6 +3189,10 @@ sealed interface KaFirDiagnostic<PSI : PsiElement> : KaDiagnosticWithPsi<PSI> {
         override val diagnosticClass get() = TypecheckerHasRunIntoRecursiveProblem::class
     }
 
+    interface ReturnValueNotUsed : KaFirDiagnostic<KtElement> {
+        override val diagnosticClass get() = ReturnValueNotUsed::class
+    }
+
     interface UnsafeCall : KaFirDiagnostic<PsiElement> {
         override val diagnosticClass get() = UnsafeCall::class
         val receiverType: KaType

analysis/analysis-api-fir/src/org/jetbrains/kotlin/analysis/api/fir/diagnostics/KaFirDiagnosticsImpl.kt

@@ -3835,6 +3835,11 @@ internal class TypecheckerHasRunIntoRecursiveProblemImpl(
     token: KaLifetimeToken,
 ) : KaAbstractFirDiagnostic<KtExpression>(firDiagnostic, token), KaFirDiagnostic.TypecheckerHasRunIntoRecursiveProblem
 
+internal class ReturnValueNotUsedImpl(
+    firDiagnostic: KtPsiDiagnostic,
+    token: KaLifetimeToken,
+) : KaAbstractFirDiagnostic<KtElement>(firDiagnostic, token), KaFirDiagnostic.ReturnValueNotUsed
+
 internal class UnsafeCallImpl(
     override val receiverType: KaType,
     override val receiverExpression: KtExpression?,

analysis/low-level-api-fir/tests/org/jetbrains/kotlin/analysis/low/level/api/fir/diagnostic/compiler/based/LLDiagnosticsFe10TestGenerated.java

@@ -72,6 +72,7 @@ fun copyCommonCompilerArguments(from: CommonCompilerArguments, to: CommonCompile
     to.reportAllWarnings = from.reportAllWarnings
     to.reportOutputFiles = from.reportOutputFiles
     to.reportPerf = from.reportPerf
+    to.returnValueChecker = from.returnValueChecker
     to.script = from.script
     to.selfUpperBoundInference = from.selfUpperBoundInference
     to.skipMetadataVersionCheck = from.skipMetadataVersionCheck

analysis/low-level-api-fir/tests/org/jetbrains/kotlin/analysis/low/level/api/fir/diagnostic/compiler/based/LLReversedDiagnosticsFe10TestGenerated.java

@@ -574,6 +574,17 @@ This flag partially enables functionality of `-Xexplicit-api` flag, so please do
             field = value
         }
 
+    @Argument(
+        value = "-Xreturn-value-checker",
+        valueDescription = "{check|full|disable}",
+        description = """Set improved unused return value checker mode. Use 'check' to run checker only and use 'full' to also enable automatic annotation insertion."""
+    )
+    var returnValueChecker: String = ReturnValueCheckerMode.DISABLED.state
+        set(value) {
+            checkFrozen()
+            field = value
+        }
+
     @Argument(
         value = "-Xinference-compatibility",
         description = "Enable compatibility changes for the generic type inference algorithm."
@@ -909,6 +920,10 @@ default: 'first-only-warn' in language version 2.2+, 'first-only' in version 2.1
             put(AnalysisFlags.allowFullyQualifiedNameInKClass, true)
             put(AnalysisFlags.dontWarnOnErrorSuppression, dontWarnOnErrorSuppression)
             fillWarningLevelMap(collector)
+            ReturnValueCheckerMode.fromString(returnValueChecker)?.also { put(AnalysisFlags.returnValueCheckerMode, it) } ?: collector.report(
+                CompilerMessageSeverity.ERROR,
+                "Unknown value for parameter -Xreturn-value-checker: '$returnValueChecker'. Value should be one of ${ReturnValueCheckerMode.availableValues()}"
+            )
         }
     }
 

compiler/cli/cli-common/gen/org/jetbrains/kotlin/cli/common/arguments/CommonCompilerArgumentsCopyGenerated.kt

@@ -88,6 +88,9 @@ object AnalysisFlags {
     val expandTypeAliasesInTypeResolution by AnalysisFlag.Delegates.Boolean(defaultValue = true)
 
     val warningLevels by AnalysisFlag.Delegates.WarningLevelMap
+
+    @JvmStatic
+    val returnValueCheckerMode by AnalysisFlag.Delegates.ReturnValueCheckerDisabledByDefault
 }
 
 @Deprecated(