Add observer feature for Scope lifecycle tracking

compiler/build.gradle

@@ -32,4 +32,5 @@ dependencies {
 
 test {
     inputs.files(file("$rootDir/tests/src"))
+    environment "MOTIF_OBSERVE", "1"
 }

compiler/src/main/kotlin/motif/compiler/JavaCodeGenerator.kt

@@ -30,6 +30,7 @@ import com.uber.xprocessing.ext.withRawTypeFix
 import javax.lang.model.element.Modifier
 import javax.lang.model.type.DeclaredType
 import motif.internal.None
+import motif.observe.MotifObserver
 
 object JavaCodeGenerator {
 
@@ -47,12 +48,17 @@ object JavaCodeGenerator {
             objectsField?.let { addField(it.spec()) }
             addField(dependenciesField.spec())
             cacheFields.forEach { addField(it.spec(useNullFieldInitialization)) }
-            addMethod(constructor.spec())
+            val scopeNameString = superClassName.j.toString()
+            addMethod(constructor.spec(shouldGenerateObserverCode, scopeNameString))
             alternateConstructor?.let { addMethod(it.spec()) }
             accessMethodImpls.forEach { addMethod(it.spec()) }
             childMethodImpls.forEach { addMethod(it.spec()) }
             addMethod(scopeProviderMethod.spec())
-            factoryProviderMethods.forEach { addMethods(it.specs(useNullFieldInitialization)) }
+            factoryProviderMethods.forEach {
+              addMethods(
+                  it.specs(useNullFieldInitialization, shouldGenerateObserverCode, scopeNameString),
+              )
+            }
             dependencyProviderMethods.forEach { addMethod(it.spec()) }
             dependencies?.let { addType(it.spec()) }
             objectsImpl?.let { addType(it.spec()) }
@@ -96,6 +102,22 @@ object JavaCodeGenerator {
           .addStatement("this.\$N = \$N", dependenciesFieldName, dependenciesParameterName)
           .build()
 
+  private fun Constructor.spec(shouldGenerateObserverCode: Boolean, scopeName: String): MethodSpec =
+      MethodSpec.constructorBuilder()
+          .addModifiers(Modifier.PUBLIC)
+          .addParameter(dependenciesClassName.j, dependenciesParameterName)
+          .apply {
+            if (shouldGenerateObserverCode) {
+              addStatement(
+                  "\$T.notifyScopeInitializing(\$S)",
+                  MotifObserver::class.java,
+                  scopeName,
+              )
+            }
+            addStatement("this.\$N = \$N", dependenciesFieldName, dependenciesParameterName)
+          }
+          .build()
+
   private fun AlternateConstructor.spec(): MethodSpec =
       MethodSpec.constructorBuilder()
           .addModifiers(Modifier.PUBLIC)
@@ -168,11 +190,36 @@ object JavaCodeGenerator {
   private fun ScopeProviderMethod.spec(): MethodSpec =
       MethodSpec.methodBuilder(name).returns(scopeClassName.j).addStatement("return this").build()
 
-  private fun FactoryProviderMethod.specs(useNullFieldInitialization: Boolean): List<MethodSpec> {
+  private fun FactoryProviderMethod.specs(
+      useNullFieldInitialization: Boolean,
+      shouldGenerateObserverCode: Boolean,
+      scopeName: String,
+  ): List<MethodSpec> {
     val primarySpec =
         MethodSpec.methodBuilder(name)
             .returns(returnTypeName.j)
-            .addStatement(body.spec(useNullFieldInitialization))
+            .apply {
+              if (shouldGenerateObserverCode) {
+                addStatement(
+                    "\$T.notifyProvideStart(\$S, \$S)",
+                    MotifObserver::class.java,
+                    scopeName,
+                    name,
+                )
+                beginControlFlow("try")
+                addStatement(body.spec(useNullFieldInitialization))
+                nextControlFlow("finally")
+                addStatement(
+                    "\$T.notifyProvideComplete(\$S, \$S)",
+                    MotifObserver::class.java,
+                    scopeName,
+                    name,
+                )
+                endControlFlow()
+              } else {
+                addStatement(body.spec(useNullFieldInitialization))
+              }
+            }
             .build()
     val spreadSpecs = spreadProviderMethods.map { it.spec() }
     return listOf(primarySpec) + spreadSpecs

compiler/src/main/kotlin/motif/compiler/KotlinCodeGenerator.kt

@@ -31,6 +31,7 @@ import com.squareup.kotlinpoet.asTypeName
 import com.squareup.kotlinpoet.javapoet.KotlinPoetJavaPoetPreview
 import com.squareup.kotlinpoet.javapoet.toKClassName
 import motif.internal.None
+import motif.observe.MotifObserver
 
 @OptIn(KotlinPoetJavaPoetPreview::class)
 object KotlinCodeGenerator {
@@ -50,7 +51,8 @@ object KotlinCodeGenerator {
             objectsField?.let { addProperty(it.spec()) }
             addProperty(dependenciesField.spec())
             cacheFields.forEach { addProperty(it.spec(useNullFieldInitialization)) }
-            primaryConstructor(constructor.spec())
+            val scopeNameString = superClassName.kt.toString()
+            primaryConstructor(constructor.spec(shouldGenerateObserverCode, scopeNameString))
             alternateConstructor?.let { addFunction(it.spec()) }
             accessMethodImpls
                 .filter { !it.overriddenMethod.isSynthetic }
@@ -60,7 +62,11 @@ object KotlinCodeGenerator {
                 .forEach { addProperty(it.propSpec()) }
             childMethodImpls.forEach { addFunction(it.spec()) }
             addFunction(scopeProviderMethod.spec())
-            factoryProviderMethods.forEach { addFunctions(it.specs(useNullFieldInitialization)) }
+            factoryProviderMethods.forEach {
+              addFunctions(
+                  it.specs(useNullFieldInitialization, shouldGenerateObserverCode, scopeNameString),
+              )
+            }
             dependencyProviderMethods.forEach { addFunction(it.spec()) }
             dependencies?.let { addType(it.spec()) }
             objectsImpl?.let { addType(it.spec()) }
@@ -112,9 +118,18 @@ object KotlinCodeGenerator {
             .build()
       }
 
-  private fun Constructor.spec(): FunSpec =
+  private fun Constructor.spec(shouldGenerateObserverCode: Boolean, scopeName: String): FunSpec =
       FunSpec.constructorBuilder()
           .addParameter(dependenciesParameterName, dependenciesClassName.kt)
+          .apply {
+            if (shouldGenerateObserverCode) {
+              addStatement(
+                  "%T.notifyScopeInitializing(%S)",
+                  MotifObserver::class,
+                  scopeName,
+              )
+            }
+          }
           .build()
 
   private fun AlternateConstructor.spec(): FunSpec =
@@ -203,12 +218,37 @@ object KotlinCodeGenerator {
           .addStatement("return this")
           .build()
 
-  private fun FactoryProviderMethod.specs(useNullFieldInitialization: Boolean): List<FunSpec> {
+  private fun FactoryProviderMethod.specs(
+      useNullFieldInitialization: Boolean,
+      shouldGenerateObserverCode: Boolean,
+      scopeName: String,
+  ): List<FunSpec> {
     val primarySpec =
         FunSpec.builder(name)
             .addModifiers(KModifier.INTERNAL)
             .returns(returnTypeName.reloadedForTypeArgs(env))
-            .addCode(body.spec(useNullFieldInitialization))
+            .apply {
+              if (shouldGenerateObserverCode) {
+                addStatement(
+                    "%T.notifyProvideStart(%S, %S)",
+                    MotifObserver::class,
+                    scopeName,
+                    name,
+                )
+                beginControlFlow("try")
+                addCode(body.spec(useNullFieldInitialization))
+                nextControlFlow("finally")
+                addStatement(
+                    "%T.notifyProvideComplete(%S, %S)",
+                    MotifObserver::class,
+                    scopeName,
+                    name,
+                )
+                endControlFlow()
+              } else {
+                addCode(body.spec(useNullFieldInitialization))
+              }
+            }
             .build()
     val spreadSpecs = spreadProviderMethods.map { it.spec() }
     return listOf(primarySpec) + spreadSpecs

compiler/src/main/kotlin/motif/compiler/ScopeImpl.kt

@@ -36,6 +36,8 @@ import motif.ast.compiler.CompilerMethod
  */
 class ScopeImpl(
     val useNullFieldInitialization: Boolean,
+    val enableObserver: Boolean,
+    val shouldGenerateObserverCode: Boolean,
     val className: ClassName,
     val superClassName: ClassName,
     val internalScope: Boolean,

compiler/src/main/kotlin/motif/compiler/ScopeImplFactory.kt

@@ -67,11 +67,16 @@ private constructor(
 
     fun create(): ScopeImpl {
       val isInternal = (scope.clazz as? CompilerClass)?.isInternal() ?: false
+      val scopeAnnotation =
+          scope.clazz.annotations.find { it.className == motif.Scope::class.java.name }!!
+      // Observer code is only generated if both the annotation is enabled AND the environment
+      // variable is set
+      val shouldGenerateObserverCode = scope.enableObserver && OBSERVER_ENABLED
       return ScopeImpl(
-          (scope.clazz.annotations
-              .find { it.className == motif.Scope::class.java.name }!!
-              .annotationValueMap[SCOPE_ANNOTATION_FIELD_USE_NULL]
-              as? Boolean) ?: false,
+          (scopeAnnotation.annotationValueMap[SCOPE_ANNOTATION_FIELD_USE_NULL] as? Boolean)
+              ?: false,
+          scope.enableObserver,
+          shouldGenerateObserverCode,
           scope.implClassName,
           scope.typeName,
           isInternal,
@@ -435,6 +440,12 @@ private constructor(
     private const val DEPENDENCIES_FIELD_NAME = "dependencies"
     private const val SCOPE_ANNOTATION_FIELD_USE_NULL = "useNullFieldInitialization"
 
+    // Check environment variable once for observer code generation
+    private val OBSERVER_ENABLED: Boolean by lazy {
+      val envValue = System.getenv("MOTIF_OBSERVE")
+      envValue == "1" || envValue.equals("True", ignoreCase = true)
+    }
+
     fun create(env: XProcessingEnv, graph: ResolvedGraph): List<ScopeImpl> =
         ScopeImplFactory(env, graph).create()
   }

lib/src/main/java/motif/Scope.java

@@ -21,4 +21,7 @@
    *     [Initialized.INITIALIZED] will be used to skip the field initialization.
    */
   boolean useNullFieldInitialization() default false;
+
+  /** @return true if this scope should register with MotifObserver and fire lifecycle events. */
+  boolean enableObserver() default false;
 }

lib/src/main/java/motif/observe/MotifObserver.java

@@ -0,0 +1,110 @@
+/*
+ * Copyright (c) 2018-2019 Uber Technologies, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package motif.observe;
+
+import java.util.List;
+import java.util.concurrent.CopyOnWriteArrayList;
+
+/**
+ * Central registry for Motif observers. This class manages a list of {@link Observer} instances and
+ * dispatches lifecycle events to all registered observers.
+ *
+ * <p>Events are not cached, observers will only receive events post registration.
+ *
+ * <p>This class is thread-safe.
+ *
+ * <p>Use -motif.
+ */
+public final class MotifObserver {
+
+  private static final List<Observer> observers = new CopyOnWriteArrayList<>();
+
+  private MotifObserver() {
+    // Prevent instantiation
+  }
+
+  /**
+   * Registers an observer to receive lifecycle events from Motif scopes.
+   *
+   * @param observer the observer to register
+   */
+  public static void register(Observer observer) {
+    if (observer != null && !observers.contains(observer)) {
+      observers.add(observer);
+    }
+  }
+
+  /**
+   * Unregisters an observer so it no longer receives lifecycle events.
+   *
+   * @param observer the observer to unregister
+   */
+  public static void unregister(Observer observer) {
+    observers.remove(observer);
+  }
+
+  /** Clears all registered observers. */
+  public static void clearAll() {
+    observers.clear();
+  }
+
+  /**
+   * Called by generated ScopeImpl classes when a scope is being initialized.
+   *
+   * @param scopeClassName the fully qualified name of the scope being initialized
+   */
+  public static void notifyScopeInitializing(String scopeClassName) {
+    for (Observer observer : observers) {
+      try {
+        observer.onScopeInitializing(scopeClassName);
+      } catch (Exception e) {
+        // Silently catch exceptions to prevent observer issues from breaking scope initialization
+      }
+    }
+  }
+
+  /**
+   * Called by generated ScopeImpl classes when a factory/provider method is about to be invoked.
+   *
+   * @param scopeClassName the fully qualified name of the scope
+   * @param methodName the name of the factory/provider method
+   */
+  public static void notifyProvideStart(String scopeClassName, String methodName) {
+    for (Observer observer : observers) {
+      try {
+        observer.onProvideStart(scopeClassName, methodName);
+      } catch (Exception e) {
+        // Silently catch exceptions to prevent observer issues from breaking scope functionality
+      }
+    }
+  }
+
+  /**
+   * Called by generated ScopeImpl classes when a factory/provider method has completed execution.
+   *
+   * @param scopeClassName the fully qualified name of the scope
+   * @param methodName the name of the factory/provider method
+   */
+  public static void notifyProvideComplete(String scopeClassName, String methodName) {
+    for (Observer observer : observers) {
+      try {
+        observer.onProvideComplete(scopeClassName, methodName);
+      } catch (Exception e) {
+        // Silently catch exceptions to prevent observer issues from breaking scope functionality
+      }
+    }
+  }
+}

lib/src/main/java/motif/observe/Observer.java

@@ -0,0 +1,46 @@
+/*
+ * Copyright (c) 2018-2019 Uber Technologies, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package motif.observe;
+
+/**
+ * Observer interface for tracking Scope lifecycle events. Implementations can be registered via
+ * {@link MotifObserver#register(Observer)}.
+ */
+public interface Observer {
+
+  /**
+   * Called when a Scope implementation is being initialized.
+   *
+   * @param scopeClassName the fully qualified name of the scope being initialized
+   */
+  void onScopeInitializing(String scopeClassName);
+
+  /**
+   * Called when a factory/provider method is about to be invoked.
+   *
+   * @param scopeClassName the fully qualified name of the scope
+   * @param methodName the name of the factory/provider method
+   */
+  void onProvideStart(String scopeClassName, String methodName);
+
+  /**
+   * Called when a factory/provider method has completed execution.
+   *
+   * @param scopeClassName the fully qualified name of the scope
+   * @param methodName the name of the factory/provider method
+   */
+  void onProvideComplete(String scopeClassName, String methodName);
+}