Introduce deprecation of companion objects nested classes

Introdude deprecation as per KT-21515. Warning is reported on type
usage, that soon will became invisible. Quickfix by adding explicit
import is added.

Idea behind implementation is to mark scopes that are deprecated (see
ClassResolutionScopesSupport).

Then, during walk along hierarchy of scopes, look at deprecation status
of the scope that has provided this classifier.
Note that we also have to check if there are *some* non-deprecated
visibility paths (because we can see classifier by two paths, e.g. if
we've added explicit import) -- then this type reference shouldn't be
treated as deprecated.

core/descriptors/src/org/jetbrains/kotlin/descriptors/DescriptorWithDeprecation.kt

@@ -0,0 +1,17 @@
+/*
+ * Copyright 2000-2018 JetBrains s.r.o. 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.descriptors
+
+data class DescriptorWithDeprecation<out T : DeclarationDescriptor>(val descriptor: T, val isDeprecated: Boolean) {
+    companion object {
+        fun <T : DeclarationDescriptor> createNonDeprecated(descriptor: T): DescriptorWithDeprecation<T> =
+            DescriptorWithDeprecation(descriptor, false)
+
+        fun <T : DeclarationDescriptor> createDeprecated(descriptor: T): DescriptorWithDeprecation<T> =
+            DescriptorWithDeprecation(descriptor, true)
+    }
+}
+

core/descriptors/src/org/jetbrains/kotlin/resolve/scopes/ResolutionScope.kt

@@ -16,17 +16,29 @@
 
 package org.jetbrains.kotlin.resolve.scopes
 
-import org.jetbrains.kotlin.descriptors.ClassifierDescriptor
-import org.jetbrains.kotlin.descriptors.DeclarationDescriptor
-import org.jetbrains.kotlin.descriptors.FunctionDescriptor
-import org.jetbrains.kotlin.descriptors.VariableDescriptor
+import org.jetbrains.kotlin.descriptors.*
 import org.jetbrains.kotlin.incremental.components.LookupLocation
 import org.jetbrains.kotlin.name.Name
 
 interface ResolutionScope {
-
+    /**
+     * Returns only non-deprecated classifiers.
+     *
+     * See [getContributedClassifierIncludeDeprecated] to get all classifiers.
+     */
     fun getContributedClassifier(name: Name, location: LookupLocation): ClassifierDescriptor?
 
+    /**
+     * Returns contributed classifier, but discriminates deprecated
+     *
+     * This method can return some classifier where [getContributedClassifier] haven't returned none,
+     * but it should never return different one, even if it is deprecated.
+     * Note that implementors are encouraged to provide non-deprecated classifier if it doesn't contradict
+     * contract above.
+     */
+    fun getContributedClassifierIncludeDeprecated(name: Name, location: LookupLocation): DescriptorWithDeprecation<ClassifierDescriptor>? =
+        getContributedClassifier(name, location)?.let { DescriptorWithDeprecation.createNonDeprecated(it) }
+
     fun getContributedVariables(name: Name, location: LookupLocation): Collection<VariableDescriptor>
 
     fun getContributedFunctions(name: Name, location: LookupLocation): Collection<FunctionDescriptor>

core/descriptors/src/org/jetbrains/kotlin/types/ErrorUtils.java

@@ -181,6 +181,14 @@ public class ErrorUtils {
             return createErrorClass(name.asString());
         }
 
+        @Nullable
+        @Override
+        public DescriptorWithDeprecation<ClassifierDescriptor> getContributedClassifierIncludeDeprecated(
+                @NotNull Name name, @NotNull LookupLocation location
+        ) {
+            return null;
+        }
+
         @NotNull
         @Override
         // TODO: Convert to Kotlin or add @JvmWildcard to MemberScope declarations
@@ -259,6 +267,14 @@ public class ErrorUtils {
             throw new IllegalStateException(debugMessage+", required name: " + name);
         }
 
+        @Nullable
+        @Override
+        public DescriptorWithDeprecation<ClassifierDescriptor> getContributedClassifierIncludeDeprecated(
+                @NotNull Name name, @NotNull LookupLocation location
+        ) {
+            throw new IllegalStateException(debugMessage + ", required name: " + name);
+        }
+
         @NotNull
         @Override
         @SuppressWarnings({"unchecked"}) // KT-9898 Impossible implement kotlin interface from java