[FIR] Report DEPRECATION when Java declaration is deprecated in javadoc

#KT-60682

compiler/fir/java/src/org/jetbrains/kotlin/fir/java/FirJavaFacade.kt

@@ -239,6 +239,9 @@ abstract class FirJavaFacade(
         return buildJavaClass {
             resolvePhase = FirResolvePhase.BODY_RESOLVE
             javaAnnotations += javaClass.annotations
+            if (javaClass.isDeprecatedInJavaDoc && javaAnnotations.none { it.isJavaDeprecatedAnnotation() }) {
+                javaAnnotations += DeprecatedInJavaDocAnnotation
+            }
             source = javaClass.toSourceElement()
             this.moduleData = moduleData
             symbol = classSymbol

compiler/fir/java/src/org/jetbrains/kotlin/fir/java/javaAnnotationsMapping.kt

@@ -53,7 +53,24 @@ internal fun Iterable<JavaAnnotation>.convertAnnotationsToFir(
 
 internal fun JavaAnnotationOwner.convertAnnotationsToFir(
     session: FirSession,
-): List<FirAnnotation> = annotations.convertAnnotationsToFir(session)
+): List<FirAnnotation> = buildList {
+    var isDeprecated = false
+
+    annotations.mapTo(this) {
+        if (it.isJavaDeprecatedAnnotation()) isDeprecated = true
+        it.toFirAnnotationCall(session)
+    }
+
+    if (!isDeprecated && isDeprecatedInJavaDoc) {
+        add(DeprecatedInJavaDocAnnotation.toFirAnnotationCall(session))
+    }
+}
+
+internal object DeprecatedInJavaDocAnnotation : JavaAnnotation {
+    override val arguments: Collection<JavaAnnotationArgument> get() = emptyList()
+    override val classId: ClassId get() = StandardClassIds.Annotations.Java.Deprecated
+    override fun resolve(): JavaClass? = null
+}
 
 internal fun FirAnnotationContainer.setAnnotationsFromJava(
     session: FirSession,
@@ -225,6 +242,10 @@ private fun fillAnnotationArgumentMapping(
     }
 }
 
+internal fun JavaAnnotation.isJavaDeprecatedAnnotation(): Boolean {
+    return classId == StandardClassIds.Annotations.Java.Deprecated
+}
+
 private fun JavaAnnotation.toFirAnnotationCall(session: FirSession): FirAnnotation = buildAnnotation {
     val lookupTag = when (classId) {
         StandardClassIds.Annotations.Java.Target -> StandardClassIds.Annotations.Target