Merge remote-tracking branch 'refs/remotes/origin/main-1.x.y'

# Conflicts:
#	api/public/src/main/kotlin/com/yandex/yatagan/internal/YataganGenerated.kt

api/public/api/public.api

@@ -131,6 +131,8 @@ public final class com/yandex/yatagan/Optional {
 	public static final fun of (Ljava/lang/Object;)Lcom/yandex/yatagan/Optional;
 	public static final fun ofNullable (Ljava/lang/Object;)Lcom/yandex/yatagan/Optional;
 	public final fun orElse (Ljava/lang/Object;)Ljava/lang/Object;
+	public final fun orElse (Ljavax/inject/Provider;)Ljava/lang/Object;
+	public final synthetic fun orElse (Lkotlin/jvm/functions/Function0;)Ljava/lang/Object;
 	public final fun orNull ()Ljava/lang/Object;
 }
 

api/public/src/main/kotlin/com/yandex/yatagan/Optional.kt

@@ -16,6 +16,7 @@
 
 package com.yandex.yatagan
 
+import javax.inject.Provider
 import kotlin.contracts.InvocationKind
 import kotlin.contracts.contract
 
@@ -101,6 +102,14 @@ public class Optional<out T : Any> private constructor(
     @JvmName("map")
     public fun <U : Any> mapJava(mapper: Function<T, U?>): Optional<U> = map(mapper::apply)
 
+    /**
+     * @see [orElse]
+     */
+    @JvmName("orElse")
+    public fun orElseJava(alternative: Provider<@UnsafeVariance T>): T {
+        return value ?: alternative.get()
+    }
+
     // endregion Java API
 
     // region Kotlin API
@@ -140,6 +149,17 @@ public class Optional<out T : Any> private constructor(
         return if (value != null) ofNullable(mapper(value)) else empty()
     }
 
+    /**
+     * Stored value access with alternative.
+     *
+     * @return stored value if present. Otherwise, returns [alternative].
+     */
+    @JvmSynthetic
+    public inline fun orElse(alternative: () -> @UnsafeVariance T): T {
+        contract { callsInPlace(alternative, InvocationKind.AT_MOST_ONCE) }
+        return value ?: alternative()
+    }
+
     // endregion Kotlin API
 
     public companion object {

api/public/src/main/kotlin/com/yandex/yatagan/internal/YataganGenerated.kt

@@ -0,0 +1,10 @@
+package com.yandex.yatagan.internal
+
+/**
+ * Marks top-level classes (currently top-level component implementations) in generated code.
+ * May reliably be used in tooling to determine whether the class was generated by Yatagan.
+ */
+@MustBeDocumented
+@Retention(AnnotationRetention.BINARY)
+@Target(AnnotationTarget.CLASS)
+public annotation class YataganGenerated

codegen/impl/src/main/kotlin/com/yandex/yatagan/codegen/impl/ComponentGenerator.kt

@@ -53,6 +53,7 @@ internal class ComponentGenerator @Inject constructor(
         val enableProvisionNullChecks: Boolean,
         val enableThreadChecks: Boolean,
         val sortMethodsForTesting: Boolean,
+        val generatedAnnotationClassName: ClassName?,
     )
 
     init {
@@ -69,12 +70,19 @@ internal class ComponentGenerator @Inject constructor(
     fun generate(): TypeSpec = buildClass(generatedClassName) {
         val componentInterface = graph.model.typeName()
 
-        annotation<SuppressWarnings> { stringValues("unchecked", "rawtypes", "NullableProblems") }
         modifiers(FINAL)
         if (!graph.isRoot) {
             modifiers(/*package-private*/ STATIC)
         } else {
             modifiers(PUBLIC)
+            annotation<SuppressWarnings> { stringValues("unchecked", "rawtypes", "NullableProblems") }
+            annotation(Names.YataganGenerated)
+            options.generatedAnnotationClassName?.let {
+                annotation(it) {
+                    // We don't use the actual processor name here, as we want the code to be the same across backends.
+                    stringValue(value = "com.yandex.yatagan.codegen.impl.ComponentGenerator")
+                }
+            }
         }
         implements(componentInterface)
 

codegen/impl/src/main/kotlin/com/yandex/yatagan/codegen/impl/ComponentGeneratorFacade.kt

@@ -16,9 +16,11 @@
 
 package com.yandex.yatagan.codegen.impl
 
+import com.squareup.javapoet.ClassName
 import com.squareup.javapoet.JavaFile
 import com.yandex.yatagan.Yatagan
 import com.yandex.yatagan.core.graph.BindingGraph
+import com.yandex.yatagan.lang.langFactory
 
 class ComponentGeneratorFacade(
     graph: BindingGraph,
@@ -27,13 +29,15 @@ class ComponentGeneratorFacade(
     enableProvisionNullChecks: Boolean,
     sortMethodsForTesting: Boolean,
 ) {
+    private val langFactory = graph.model.type.ext.langFactory
     private val component = Yatagan.builder(GeneratorComponent.Factory::class.java).create(
         graph = graph,
         options = ComponentGenerator.Options(
             maxSlotsPerSwitch = maxSlotsPerSwitch,
             enableProvisionNullChecks = enableProvisionNullChecks,
             enableThreadChecks = enableThreadChecks,
             sortMethodsForTesting = sortMethodsForTesting,
+            generatedAnnotationClassName = generatedAnnotationClassName(),
         ),
     )
 
@@ -48,4 +52,12 @@ class ComponentGeneratorFacade(
             .build()
             .writeTo(out)
     }
+
+    private fun generatedAnnotationClassName(): ClassName? {
+        return Names.GeneratedJava8.takeIf { it.exists() } ?: Names.GeneratedJava9Plus.takeIf { it.exists() }
+    }
+
+    private fun ClassName.exists(): Boolean {
+        return langFactory.getTypeDeclaration(packageName(), simpleName()) != null
+    }
 }

codegen/impl/src/main/kotlin/com/yandex/yatagan/codegen/impl/Names.kt

@@ -25,6 +25,7 @@ internal object Names {
     val AutoBuilder: ClassName = ClassName.get("com.yandex.yatagan", "AutoBuilder")
     val ThreadAssertions: ClassName = ClassName.get("com.yandex.yatagan.internal", "ThreadAssertions")
     val Checks: ClassName = ClassName.get("com.yandex.yatagan.internal", "Checks")
+    val YataganGenerated = ClassName.get("com.yandex.yatagan.internal", "YataganGenerated")
 
     val AssertionError: ClassName = ClassName.get(java.lang.AssertionError::class.java)
     val Class: ClassName = ClassName.get(java.lang.Class::class.java)
@@ -33,4 +34,7 @@ internal object Names {
     val ArrayList: ClassName = ClassName.get(java.util.ArrayList::class.java)
     val HashMap: ClassName = ClassName.get(java.util.HashMap::class.java)
     val HashSet: ClassName = ClassName.get(java.util.HashSet::class.java)
+
+    val GeneratedJava8: ClassName = ClassName.get("javax.annotation", "Generated")
+    val GeneratedJava9Plus: ClassName = ClassName.get("javax.annotation.processing", "Generated")
 }

codegen/poetry/src/main/kotlin/com/yandex/yatagan/codegen/poetry/AnnotatibleBuilder.kt

@@ -16,11 +16,14 @@
 
 package com.yandex.yatagan.codegen.poetry
 
+import com.squareup.javapoet.ClassName
 import javax.lang.model.element.AnnotationMirror
 import kotlin.reflect.KClass
 
 interface AnnotatibleBuilder {
     fun annotation(mirror: AnnotationMirror)
 
     fun annotation(clazz: KClass<out Annotation>, block: AnnotationSpecBuilder.() -> Unit)
+
+    fun annotation(className: ClassName, block: AnnotationSpecBuilder.() -> Unit)
 }

codegen/poetry/src/main/kotlin/com/yandex/yatagan/codegen/poetry/AnnotationSpecBuilder.kt

@@ -21,11 +21,12 @@ import com.squareup.javapoet.ClassName
 import kotlin.reflect.KClass
 
 @JavaPoetry
-class AnnotationSpecBuilder(
-    clazz: KClass<out Annotation>
-) {
+class AnnotationSpecBuilder private constructor(
     @PublishedApi
-    internal val impl: AnnotationSpec.Builder = AnnotationSpec.builder(clazz.java)
+    internal val impl: AnnotationSpec.Builder,
+) {
+    constructor(clazz: KClass<out Annotation>) : this(AnnotationSpec.builder(clazz.java))
+    constructor(className: ClassName) : this(AnnotationSpec.builder(className))
 
     inline fun <reified E : Enum<E>> enumValue(value: E, name: String = "value") {
         impl.addMember(name, "\$T.\$N", E::class.java, value.name)

codegen/poetry/src/main/kotlin/com/yandex/yatagan/codegen/poetry/MethodSpecBuilder.kt

@@ -66,6 +66,10 @@ abstract class MethodSpecBuilder : CodeBuilder(), AnnotatibleBuilder {
         impl.addAnnotation(AnnotationSpecBuilder(clazz).apply(block).impl.build())
     }
 
+    override fun annotation(className: ClassName, block: AnnotationSpecBuilder.() -> Unit) {
+        impl.addAnnotation(AnnotationSpecBuilder(className).apply(block).impl.build())
+    }
+
     fun returnType(type: TypeName) {
         impl.returns(type)
     }

codegen/poetry/src/main/kotlin/com/yandex/yatagan/codegen/poetry/ParameterSpecBuilder.kt

@@ -17,6 +17,7 @@
 package com.yandex.yatagan.codegen.poetry
 
 import com.squareup.javapoet.AnnotationSpec
+import com.squareup.javapoet.ClassName
 import com.squareup.javapoet.ParameterSpec
 import com.squareup.javapoet.TypeName
 import javax.lang.model.element.AnnotationMirror
@@ -43,4 +44,11 @@ class ParameterSpecBuilder constructor(type: TypeName, name: String) : Annotatib
     ) {
         impl.addAnnotation(AnnotationSpecBuilder(clazz).apply(block).impl.build())
     }
+
+    override fun annotation(
+        className: ClassName,
+        block: AnnotationSpecBuilder.() -> Unit,
+    ) {
+        impl.addAnnotation(AnnotationSpecBuilder(className).apply(block).impl.build())
+    }
 }

codegen/poetry/src/main/kotlin/com/yandex/yatagan/codegen/poetry/TypeSpecBuilder.kt

@@ -68,6 +68,13 @@ abstract class TypeSpecBuilder : AnnotatibleBuilder {
         impl.addAnnotation(AnnotationSpecBuilder(clazz).apply(block).impl.build())
     }
 
+    override fun annotation(
+        className: ClassName,
+        block: AnnotationSpecBuilder.() -> Unit,
+    ) {
+        impl.addAnnotation(AnnotationSpecBuilder(className).apply(block).impl.build())
+    }
+
     fun annotation(name: ClassName) {
         impl.addAnnotation(name)
     }

testing/tests/src/test/resources/golden/AccessControlTest/-Binds-declarations-can-be-package-private.golden-code.txt

@@ -5,12 +5,16 @@ package test;
 import com.yandex.yatagan.AutoBuilder;
 import com.yandex.yatagan.Optional;
 import com.yandex.yatagan.internal.Checks;
+import com.yandex.yatagan.internal.YataganGenerated;
 import java.lang.Class;
 import java.lang.Override;
 import java.lang.SuppressWarnings;
 import java.util.Collections;
+import javax.annotation.processing.Generated;
 
 @SuppressWarnings({"unchecked", "rawtypes", "NullableProblems"})
+@YataganGenerated
+@Generated("com.yandex.yatagan.codegen.impl.ComponentGenerator")
 public final class Yatagan$TestComponent implements TestComponent {
   final boolean mMyFeatureSEnabled = MyFeature.sEnabled;
 

testing/tests/src/test/resources/golden/ComponentCreatorFailureTest/invalid-sub-component-factory-methods.golden-code.txt

@@ -4,12 +4,16 @@ package test;
 
 import com.yandex.yatagan.AutoBuilder;
 import com.yandex.yatagan.internal.Checks;
+import com.yandex.yatagan.internal.YataganGenerated;
 import java.lang.Class;
 import java.lang.Override;
 import java.lang.SuppressWarnings;
 import java.util.Collections;
+import javax.annotation.processing.Generated;
 
 @SuppressWarnings({"unchecked", "rawtypes", "NullableProblems"})
+@YataganGenerated
+@Generated("com.yandex.yatagan.codegen.impl.ComponentGenerator")
 public final class Yatagan$RootComponent2 implements RootComponent2 {
   private Yatagan$RootComponent2() {
   }
@@ -23,7 +27,6 @@ public final class Yatagan$RootComponent2 implements RootComponent2 {
     return new AutoBuilderImpl();
   }
 
-  @SuppressWarnings({"unchecked", "rawtypes", "NullableProblems"})
   static final class SubComponent1Impl implements SubComponent1 {
     final MyDependencies mMyDependencies;
 

testing/tests/src/test/resources/golden/ComponentCreatorFailureTest/missing-creator.golden-code.txt

@@ -4,12 +4,16 @@ package test;
 
 import com.yandex.yatagan.AutoBuilder;
 import com.yandex.yatagan.internal.Checks;
+import com.yandex.yatagan.internal.YataganGenerated;
 import java.lang.Class;
 import java.lang.Override;
 import java.lang.SuppressWarnings;
 import java.util.Collections;
+import javax.annotation.processing.Generated;
 
 @SuppressWarnings({"unchecked", "rawtypes", "NullableProblems"})
+@YataganGenerated
+@Generated("com.yandex.yatagan.codegen.impl.ComponentGenerator")
 public final class Yatagan$AnotherRootComponent implements AnotherRootComponent {
   private Yatagan$AnotherRootComponent() {
   }

testing/tests/src/test/resources/golden/ComponentDependenciesKotlinTest/component-dependencies-basic-case.golden-code.txt

@@ -2,10 +2,14 @@
 Name: test/Yatagan$MyApplicationComponent.java
 package test;
 
+import com.yandex.yatagan.internal.YataganGenerated;
 import java.lang.Override;
 import java.lang.SuppressWarnings;
+import javax.annotation.processing.Generated;
 
 @SuppressWarnings({"unchecked", "rawtypes", "NullableProblems"})
+@YataganGenerated
+@Generated("com.yandex.yatagan.codegen.impl.ComponentGenerator")
 public final class Yatagan$MyApplicationComponent implements MyApplicationComponent {
   Yatagan$MyApplicationComponent() {
   }
@@ -34,13 +38,17 @@ package test;
 import com.yandex.yatagan.Lazy;
 import com.yandex.yatagan.internal.Checks;
 import com.yandex.yatagan.internal.ThreadAssertions;
+import com.yandex.yatagan.internal.YataganGenerated;
 import java.lang.AssertionError;
 import java.lang.Object;
 import java.lang.Override;
 import java.lang.SuppressWarnings;
+import javax.annotation.processing.Generated;
 import javax.inject.Provider;
 
 @SuppressWarnings({"unchecked", "rawtypes", "NullableProblems"})
+@YataganGenerated
+@Generated("com.yandex.yatagan.codegen.impl.ComponentGenerator")
 public final class Yatagan$MyActivityComponent implements MyActivityComponent {
   final MyApplicationComponent mMyApplicationComponent;
 

testing/tests/src/test/resources/golden/ComponentDependenciesKotlinTest/component-dependencies-dependency-component-instance-is-available-for-inject.golden-code.txt

@@ -2,10 +2,14 @@
 Name: test/Yatagan$MyApplicationComponent.java
 package test;
 
+import com.yandex.yatagan.internal.YataganGenerated;
 import java.lang.Override;
 import java.lang.SuppressWarnings;
+import javax.annotation.processing.Generated;
 
 @SuppressWarnings({"unchecked", "rawtypes", "NullableProblems"})
+@YataganGenerated
+@Generated("com.yandex.yatagan.codegen.impl.ComponentGenerator")
 public final class Yatagan$MyApplicationComponent implements MyApplicationComponent {
   Yatagan$MyApplicationComponent() {
   }
@@ -29,13 +33,17 @@ package test;
 import com.yandex.yatagan.Lazy;
 import com.yandex.yatagan.internal.Checks;
 import com.yandex.yatagan.internal.ThreadAssertions;
+import com.yandex.yatagan.internal.YataganGenerated;
 import java.lang.AssertionError;
 import java.lang.Object;
 import java.lang.Override;
 import java.lang.SuppressWarnings;
+import javax.annotation.processing.Generated;
 import javax.inject.Provider;
 
 @SuppressWarnings({"unchecked", "rawtypes", "NullableProblems"})
+@YataganGenerated
+@Generated("com.yandex.yatagan.codegen.impl.ComponentGenerator")
 public final class Yatagan$MyActivityComponent implements MyActivityComponent {
   final MyApplicationComponent mMyApplicationComponent;
 

testing/tests/src/test/resources/golden/ComponentDependenciesKotlinTest/plain-interfaces-are-allowed-as-dependencies.golden-code.txt

@@ -3,10 +3,14 @@ Name: test/Yatagan$MyComponent.java
 package test;
 
 import com.yandex.yatagan.internal.Checks;
+import com.yandex.yatagan.internal.YataganGenerated;
 import java.lang.Override;
 import java.lang.SuppressWarnings;
+import javax.annotation.processing.Generated;
 
 @SuppressWarnings({"unchecked", "rawtypes", "NullableProblems"})
+@YataganGenerated
+@Generated("com.yandex.yatagan.codegen.impl.ComponentGenerator")
 public final class Yatagan$MyComponent implements MyComponent {
   final Dependencies mDependencies;
 

testing/tests/src/test/resources/golden/ComponentHierarchyKotlinTest/alias-binding-across-component-boundary.golden-code.txt

@@ -3,10 +3,14 @@ Name: test/Yatagan$TestComponent.java
 package test;
 
 import com.yandex.yatagan.internal.Checks;
+import com.yandex.yatagan.internal.YataganGenerated;
 import java.lang.Override;
 import java.lang.SuppressWarnings;
+import javax.annotation.processing.Generated;
 
 @SuppressWarnings({"unchecked", "rawtypes", "NullableProblems"})
+@YataganGenerated
+@Generated("com.yandex.yatagan.codegen.impl.ComponentGenerator")
 public final class Yatagan$TestComponent implements TestComponent {
   final MyImpl mImpl;
 
@@ -23,7 +27,6 @@ public final class Yatagan$TestComponent implements TestComponent {
     return new ComponentFactoryImpl();
   }
 
-  @SuppressWarnings({"unchecked", "rawtypes", "NullableProblems"})
   static final class TestSubComponentImpl implements TestSubComponent {
     final Yatagan$TestComponent mTestComponent;