Enable explicit API mode.

Author: zach-klippenstein

build.gradle.kts

@@ -106,6 +106,25 @@ subprojects {
 
 apply(from = rootProject.file(".buildscript/binary-validation.gradle"))
 
+// Require explicit public modifiers and types for actual library modules, not samples.
+allprojects.filterNot { it.path.startsWith(":samples") }
+  .forEach {
+    it.tasks.withType<KotlinCompile>().configureEach {
+      // Tests and benchmarks aren't part of the public API, don't turn explicit API mode on for
+      // them.
+      if (!name.contains("test", ignoreCase = true) &&
+        !name.contains("jmh", ignoreCase = true)
+      ) {
+        kotlinOptions {
+          // TODO this should be moved to `kotlin { explicitApi() }` once that's working for android
+          //  projects, see https://youtrack.jetbrains.com/issue/KT-37652.
+          @Suppress("SuspiciousCollectionReassignment")
+          freeCompilerArgs += "-Xexplicit-api=strict"
+        }
+      }
+    }
+  }
+
 // This is intentionally *not* applied to subprojects. When building subprojects' kdoc for maven
 // javadocs artifacts, we want to use the default config. This config is for the
 // statically-generated documentation site.

internal-testing-utils/src/main/java/com/squareup/workflow1/internal/util/UncaughtExceptionGuard.kt

@@ -16,18 +16,18 @@ import java.util.concurrent.atomic.AtomicReference
  * thrown after the block returns. If the block itself throws, that exception will be rethrown
  * directly with uncaught exceptions added to its [suppressed list][Throwable.addSuppressed].
  */
-class UncaughtExceptionGuard {
+public class UncaughtExceptionGuard {
   private val uncaughtException = AtomicReference<Throwable>()
 
-  fun reportUncaught(e: Throwable) {
+  public fun reportUncaught(e: Throwable) {
     if (!uncaughtException.compareAndSet(null, e)) {
       // If another thread beat us to it, add this exception to the suppressed list.
       // addSuppressed is thread-safe so we don't need to do any explicit synchronization.
       uncaughtException.get()!!.addSuppressedSafely(e)
     }
   }
 
-  fun <T> runRethrowingUncaught(block: () -> T): T {
+  public fun <T> runRethrowingUncaught(block: () -> T): T {
     val result = try {
       block()
     } catch (e: Throwable) {
@@ -60,7 +60,7 @@ class UncaughtExceptionGuard {
  *
  * This allows the normal JUnit exception assertion mechanisms to work with uncaught exceptions.
  */
-fun rethrowingUncaughtExceptions(block: () -> Unit) {
+public fun rethrowingUncaughtExceptions(block: () -> Unit) {
   val oldHandler = Thread.getDefaultUncaughtExceptionHandler()
   val guard = UncaughtExceptionGuard()
 

trace-encoder/src/main/java/com/squareup/tracing/TraceEncoder.kt

@@ -30,7 +30,7 @@ import kotlin.time.TimeSource
  * background thread.
  */
 @OptIn(ExperimentalTime::class)
-class TraceEncoder(
+public class TraceEncoder(
   scope: CoroutineScope,
   private val start: TimeMark = TimeSource.Monotonic.markNow(),
   ioDispatcher: CoroutineDispatcher = IO,
@@ -65,7 +65,7 @@ class TraceEncoder(
    * Note this does not do anything with _actual_ threads, it just affects the thread ID used in
    * trace events.
    */
-  fun createLogger(
+  public fun createLogger(
     processName: String = "",
     threadName: String = ""
   ): TraceLogger {

trace-encoder/src/main/java/com/squareup/tracing/TraceEvent.kt

@@ -28,66 +28,66 @@ import com.squareup.tracing.TraceEvent.ObjectSnapshot
 /**
  * Represents a single event in a trace.
  */
-sealed class TraceEvent {
+public sealed class TraceEvent {
 
-  open val category: String? get() = null
+  public open val category: String? get() = null
 
-  data class DurationBegin(
+  public data class DurationBegin(
     val name: String,
     val args: Map<String, Any?> = emptyMap(),
     override val category: String? = null
   ) : TraceEvent()
 
-  data class DurationEnd(
+  public data class DurationEnd(
     val name: String,
     val args: Map<String, Any?> = emptyMap(),
     override val category: String? = null
   ) : TraceEvent()
 
-  data class Instant(
+  public data class Instant(
     val name: String,
     val args: Map<String, Any?> = emptyMap(),
     val scope: InstantScope = THREAD,
     override val category: String? = null
   ) : TraceEvent() {
-    enum class InstantScope {
+    public enum class InstantScope {
       THREAD,
       PROCESS,
       GLOBAL
     }
   }
 
-  data class AsyncDurationBegin(
+  public data class AsyncDurationBegin(
     val id: Any,
     val name: String,
     val args: Map<String, Any?> = emptyMap(),
     override val category: String? = null
   ) : TraceEvent()
 
-  data class AsyncDurationEnd(
+  public data class AsyncDurationEnd(
     val id: Any,
     val name: String,
     val args: Map<String, Any?> = emptyMap(),
     override val category: String? = null
   ) : TraceEvent()
 
-  data class ObjectCreated(
+  public data class ObjectCreated(
     val id: Long,
     val objectType: String
   ) : TraceEvent()
 
-  data class ObjectDestroyed(
+  public data class ObjectDestroyed(
     val id: Long,
     val objectType: String
   ) : TraceEvent()
 
-  data class ObjectSnapshot(
+  public data class ObjectSnapshot(
     val id: Long,
     val objectType: String,
     val snapshot: Any
   ) : TraceEvent()
 
-  data class Counter(
+  public data class Counter(
     val name: String,
     val series: Map<String, Number>,
     val id: Long? = null

trace-encoder/src/main/java/com/squareup/tracing/TraceLogger.kt

@@ -5,17 +5,17 @@ package com.squareup.tracing
  *
  * Create with [TraceEncoder.createLogger].
  */
-interface TraceLogger {
+public interface TraceLogger {
 
   /**
    * Tags all events with the current timestamp and then enqueues them to be written to the trace
    * file.
    */
-  fun log(eventBatch: List<TraceEvent>)
+  public fun log(eventBatch: List<TraceEvent>)
 
   /**
    * Tags event with the current timestamp and then enqueues it to be written to the trace
    * file.
    */
-  fun log(event: TraceEvent)
+  public fun log(event: TraceEvent)
 }

workflow-core/src/main/java/com/squareup/workflow1/BaseRenderContext.kt

@@ -40,13 +40,13 @@ import kotlin.reflect.typeOf
  *
  * See [renderChild].
  */
-interface BaseRenderContext<out PropsT, StateT, in OutputT> {
+public interface BaseRenderContext<out PropsT, StateT, in OutputT> {
 
   /**
    * Accepts a single [WorkflowAction], invokes that action by calling [WorkflowAction.apply]
    * to update the current state, and optionally emits the returned output value if it is non-null.
    */
-  val actionSink: Sink<WorkflowAction<PropsT, StateT, OutputT>>
+  public val actionSink: Sink<WorkflowAction<PropsT, StateT, OutputT>>
 
   /**
    * Ensures [child] is running as a child of this workflow, and returns the result of its
@@ -69,7 +69,7 @@ interface BaseRenderContext<out PropsT, StateT, in OutputT> {
    * @param key An optional string key that is used to distinguish between workflows of the same
    * type.
    */
-  fun <ChildPropsT, ChildOutputT, ChildRenderingT> renderChild(
+  public fun <ChildPropsT, ChildOutputT, ChildRenderingT> renderChild(
     child: Workflow<ChildPropsT, ChildOutputT, ChildRenderingT>,
     props: ChildPropsT,
     key: String = "",
@@ -96,7 +96,7 @@ interface BaseRenderContext<out PropsT, StateT, in OutputT> {
    * @param sideEffect The suspend function that will be launched in a coroutine to perform the
    * side effect.
    */
-  fun runningSideEffect(
+  public fun runningSideEffect(
     key: String,
     sideEffect: suspend () -> Unit
   )
@@ -113,7 +113,7 @@ interface BaseRenderContext<out PropsT, StateT, in OutputT> {
    * as a debugging aid
    * @param update Function that defines the workflow update.
    */
-  fun eventHandler(
+  public fun eventHandler(
     name: () -> String = { "eventHandler" },
     update: WorkflowAction<PropsT, StateT, OutputT>.Updater.() -> Unit
   ): () -> Unit {
@@ -122,7 +122,7 @@ interface BaseRenderContext<out PropsT, StateT, in OutputT> {
     }
   }
 
-  fun <EventT> eventHandler(
+  public fun <EventT> eventHandler(
     name: () -> String = { "eventHandler" },
     update: WorkflowAction<PropsT, StateT, OutputT>.Updater.(EventT) -> Unit
   ): (EventT) -> Unit {
@@ -131,7 +131,7 @@ interface BaseRenderContext<out PropsT, StateT, in OutputT> {
     }
   }
 
-  fun <E1, E2> eventHandler(
+  public fun <E1, E2> eventHandler(
     name: () -> String = { "eventHandler" },
     update: WorkflowAction<PropsT, StateT, OutputT>.Updater.(E1, E2) -> Unit
   ): (E1, E2) -> Unit {
@@ -140,7 +140,7 @@ interface BaseRenderContext<out PropsT, StateT, in OutputT> {
     }
   }
 
-  fun <E1, E2, E3> eventHandler(
+  public fun <E1, E2, E3> eventHandler(
     name: () -> String = { "eventHandler" },
     update: WorkflowAction<PropsT, StateT, OutputT>.Updater.(E1, E2, E3) -> Unit
   ): (E1, E2, E3) -> Unit {
@@ -149,7 +149,7 @@ interface BaseRenderContext<out PropsT, StateT, in OutputT> {
     }
   }
 
-  fun <E1, E2, E3, E4> eventHandler(
+  public fun <E1, E2, E3, E4> eventHandler(
     name: () -> String = { "eventHandler" },
     update: WorkflowAction<PropsT, StateT, OutputT>.Updater.(E1, E2, E3, E4) -> Unit
   ): (E1, E2, E3, E4) -> Unit {
@@ -158,7 +158,7 @@ interface BaseRenderContext<out PropsT, StateT, in OutputT> {
     }
   }
 
-  fun <E1, E2, E3, E4, E5> eventHandler(
+  public fun <E1, E2, E3, E4, E5> eventHandler(
     name: () -> String = { "eventHandler" },
     update: WorkflowAction<PropsT, StateT, OutputT>.Updater.(E1, E2, E3, E4, E5) -> Unit
   ): (E1, E2, E3, E4, E5) -> Unit {
@@ -167,7 +167,7 @@ interface BaseRenderContext<out PropsT, StateT, in OutputT> {
     }
   }
 
-  fun <E1, E2, E3, E4, E5, E6> eventHandler(
+  public fun <E1, E2, E3, E4, E5, E6> eventHandler(
     name: () -> String = { "eventHandler" },
     update: WorkflowAction<PropsT, StateT, OutputT>.Updater.(E1, E2, E3, E4, E5, E6) -> Unit
   ): (E1, E2, E3, E4, E5, E6) -> Unit {
@@ -176,7 +176,7 @@ interface BaseRenderContext<out PropsT, StateT, in OutputT> {
     }
   }
 
-  fun <E1, E2, E3, E4, E5, E6, E7> eventHandler(
+  public fun <E1, E2, E3, E4, E5, E6, E7> eventHandler(
     name: () -> String = { "eventHandler" },
     update: WorkflowAction<PropsT, StateT, OutputT>.Updater.(E1, E2, E3, E4, E5, E6, E7) -> Unit
   ): (E1, E2, E3, E4, E5, E6, E7) -> Unit {
@@ -185,7 +185,7 @@ interface BaseRenderContext<out PropsT, StateT, in OutputT> {
     }
   }
 
-  fun <E1, E2, E3, E4, E5, E6, E7, E8> eventHandler(
+  public fun <E1, E2, E3, E4, E5, E6, E7, E8> eventHandler(
     name: () -> String = { "eventHandler" },
     update: WorkflowAction<PropsT, StateT, OutputT>.Updater.(E1, E2, E3, E4, E5, E6, E7, E8) -> Unit
   ): (E1, E2, E3, E4, E5, E6, E7, E8) -> Unit {
@@ -194,7 +194,7 @@ interface BaseRenderContext<out PropsT, StateT, in OutputT> {
     }
   }
 
-  fun <E1, E2, E3, E4, E5, E6, E7, E8, E9> eventHandler(
+  public fun <E1, E2, E3, E4, E5, E6, E7, E8, E9> eventHandler(
     name: () -> String = { "eventHandler" },
     update: WorkflowAction<PropsT, StateT, OutputT>
     .Updater.(E1, E2, E3, E4, E5, E6, E7, E8, E9) -> Unit
@@ -204,7 +204,7 @@ interface BaseRenderContext<out PropsT, StateT, in OutputT> {
     }
   }
 
-  fun <E1, E2, E3, E4, E5, E6, E7, E8, E9, E10> eventHandler(
+  public fun <E1, E2, E3, E4, E5, E6, E7, E8, E9, E10> eventHandler(
     name: () -> String = { "eventHandler" },
     update: WorkflowAction<PropsT, StateT, OutputT>
     .Updater.(E1, E2, E3, E4, E5, E6, E7, E8, E9, E10) -> Unit
@@ -217,7 +217,7 @@ interface BaseRenderContext<out PropsT, StateT, in OutputT> {
 
 @Deprecated("Use eventHandler.")
 @Suppress("DEPRECATION")
-fun <EventT : Any, PropsT, StateT, OutputT> BaseRenderContext<PropsT, StateT, OutputT>.onEvent(
+public fun <EventT : Any, PropsT, StateT, OutputT> BaseRenderContext<PropsT, StateT, OutputT>.onEvent(
   handler: (EventT) -> WorkflowAction<PropsT, StateT, OutputT>
 ): (EventT) -> Unit = EventHandler { event ->
   // Run the handler synchronously, so we only have to emit the resulting action and don't
@@ -230,7 +230,7 @@ fun <EventT : Any, PropsT, StateT, OutputT> BaseRenderContext<PropsT, StateT, Ou
  * Convenience alias of [RenderContext.renderChild] for workflows that don't take props.
  */
 /* ktlint-disable parameter-list-wrapping */
-fun <PropsT, StateT, OutputT, ChildOutputT, ChildRenderingT>
+public fun <PropsT, StateT, OutputT, ChildOutputT, ChildRenderingT>
     BaseRenderContext<PropsT, StateT, OutputT>.renderChild(
   child: Workflow<Unit, ChildOutputT, ChildRenderingT>,
   key: String = "",
@@ -242,7 +242,7 @@ fun <PropsT, StateT, OutputT, ChildOutputT, ChildRenderingT>
  * Convenience alias of [RenderContext.renderChild] for workflows that don't emit output.
  */
 /* ktlint-disable parameter-list-wrapping */
-fun <PropsT, ChildPropsT, StateT, OutputT, ChildRenderingT>
+public fun <PropsT, ChildPropsT, StateT, OutputT, ChildRenderingT>
     BaseRenderContext<PropsT, StateT, OutputT>.renderChild(
   child: Workflow<ChildPropsT, Nothing, ChildRenderingT>,
   props: ChildPropsT,
@@ -255,7 +255,7 @@ fun <PropsT, ChildPropsT, StateT, OutputT, ChildRenderingT>
  * output.
  */
 /* ktlint-disable parameter-list-wrapping */
-fun <PropsT, StateT, OutputT, ChildRenderingT>
+public fun <PropsT, StateT, OutputT, ChildRenderingT>
     BaseRenderContext<PropsT, StateT, OutputT>.renderChild(
   child: Workflow<Unit, Nothing, ChildRenderingT>,
   key: String = ""
@@ -271,7 +271,7 @@ fun <PropsT, StateT, OutputT, ChildRenderingT>
  * @param key An optional string key that is used to distinguish between identical [Worker]s.
  */
 /* ktlint-disable parameter-list-wrapping */
-inline fun <reified W : Worker<Nothing>, PropsT, StateT, OutputT>
+public inline fun <reified W : Worker<Nothing>, PropsT, StateT, OutputT>
     BaseRenderContext<PropsT, StateT, OutputT>.runningWorker(
   worker: W,
   key: String = ""
@@ -300,7 +300,7 @@ inline fun <reified W : Worker<Nothing>, PropsT, StateT, OutputT>
  */
 @OptIn(ExperimentalStdlibApi::class)
 /* ktlint-disable parameter-list-wrapping */
-inline fun <T, reified W : Worker<T>, PropsT, StateT, OutputT>
+public inline fun <T, reified W : Worker<T>, PropsT, StateT, OutputT>
     BaseRenderContext<PropsT, StateT, OutputT>.runningWorker(
   worker: W,
   key: String = "",
@@ -338,7 +338,7 @@ internal fun <T, PropsT, StateT, OutputT>
  * event types to be mapped to anonymous [WorkflowAction]s.
  */
 @Deprecated("Use BaseRenderContext.eventHandler")
-fun <EventT, PropsT, StateT, OutputT> BaseRenderContext<PropsT, StateT, OutputT>.makeEventSink(
+public fun <EventT, PropsT, StateT, OutputT> BaseRenderContext<PropsT, StateT, OutputT>.makeEventSink(
   update: WorkflowAction<PropsT, StateT, OutputT>.Updater.(EventT) -> Unit
 ): Sink<EventT> = actionSink.contraMap { event ->
   action({ "eventSink($event)" }) { update(event) }
@@ -355,8 +355,8 @@ fun <EventT, PropsT, StateT, OutputT> BaseRenderContext<PropsT, StateT, OutputT>
     "Use runningWorker",
     ReplaceWith("runningWorker(worker, key, handler)", "com.squareup.workflow1.runningWorker")
 )
-inline fun <PropsT, StateT, OutputT, reified T> BaseRenderContext<PropsT, StateT, OutputT>.onWorkerOutput(
+public inline fun <PropsT, StateT, OutputT, reified T> BaseRenderContext<PropsT, StateT, OutputT>.onWorkerOutput(
   worker: Worker<T>,
   key: String = "",
   noinline handler: (T) -> WorkflowAction<PropsT, StateT, OutputT>
-) = runningWorker(worker, key, handler)
+): Unit = runningWorker(worker, key, handler)

workflow-core/src/main/java/com/squareup/workflow1/EventHandler.kt

@@ -15,9 +15,9 @@ package com.squareup.workflow1
  * entire rendering types at once and not field-by-field.
  */
 @Deprecated("Use RenderContext.actionSink")
-class EventHandler<in EventT>(private val handler: (EventT) -> Unit) : (EventT) -> Unit {
+public class EventHandler<in EventT>(private val handler: (EventT) -> Unit) : (EventT) -> Unit {
 
-  override fun invoke(event: EventT) = handler(event)
+  override fun invoke(event: EventT): Unit = handler(event)
 
   /**
    * Returns `true` iff `other` is an [EventHandler] – all [EventHandler]s are considered equal.
@@ -40,4 +40,4 @@ class EventHandler<in EventT>(private val handler: (EventT) -> Unit) : (EventT)
  * [EventHandler]s of type `Unit` are effectively no-arg functions, so this override lets you
  * invoke them without passing the `Unit` argument.
  */
-operator fun EventHandler<Unit>.invoke() = invoke(Unit)
+public operator fun EventHandler<Unit>.invoke(): Unit = invoke(Unit)