feat(analytics-events): share the analytics event contract

.github/workflows/shared-core-tests.yml

@@ -12,6 +12,9 @@ on:
       - 'libs/currency-math/**'
       - 'libs/encryption/**'
       - 'libs/reporting/**'
+      - 'libs/analytics-events/**'
+      - 'build-logic/convention/src/main/kotlin/AnalyticsCatalogueConventionPlugin.kt'
+      - 'build-logic/convention/src/main/kotlin/com/getcode/buildlogic/analytics/**'
       - 'gradle/libs.versions.toml'
       - '.github/workflows/shared-core-tests.yml'
 
@@ -65,6 +68,7 @@ jobs:
       - name: Run the Kotlin tests on the iOS simulator target
         run: |
           ./gradlew \
+            :libs:analytics-events:iosSimulatorArm64Test \
             :libs:codes:kikcode:iosSimulatorArm64Test \
             :libs:currency-math:discrete-curve:iosSimulatorArm64Test \
             :libs:encryption:base58:iosSimulatorArm64Test \

build-logic/convention/build.gradle.kts

@@ -21,6 +21,10 @@ dependencies {
     compileOnly(libs.compose.compiler.gradle.plugin)
     compileOnly(libs.kotlin.serialization.gradle.plugin)
     compileOnly(libs.kover.gradle.plugin)
+
+    implementation(libs.tomlj)
+
+    testImplementation(kotlin("test-junit"))
 }
 
 gradlePlugin {
@@ -49,5 +53,9 @@ gradlePlugin {
             id = "flipcash.kmp.test.fixtures"
             implementationClass = "KmpTestFixturesConventionPlugin"
         }
+        register("analyticsCatalogue") {
+            id = "flipcash.analytics.catalogue"
+            implementationClass = "AnalyticsCatalogueConventionPlugin"
+        }
     }
 }

build-logic/convention/src/main/kotlin/AnalyticsCatalogueConventionPlugin.kt

@@ -0,0 +1,60 @@
+import com.getcode.buildlogic.analytics.CheckAnalyticsEventsPage
+import com.getcode.buildlogic.analytics.GenerateAnalyticsEvents
+import com.getcode.buildlogic.analytics.WriteAnalyticsEventsPage
+import org.gradle.api.Plugin
+import org.gradle.api.Project
+import org.gradle.kotlin.dsl.configure
+import org.gradle.kotlin.dsl.register
+import org.jetbrains.kotlin.gradle.dsl.KotlinMultiplatformExtension
+
+/**
+ * Generates a KMP module's analytics builders and value enums from its `events.toml` into
+ * `commonMain`, so both apps call the same Kotlin and the catalogue is the only place an event
+ * is written down. See `com.getcode.buildlogic.analytics` for the format.
+ *
+ * Usage in a module's `build.gradle.kts`:
+ * ```
+ * plugins {
+ *     alias(libs.plugins.flipcash.analytics.catalogue)
+ * }
+ * ```
+ *
+ * The generated directory is registered on `commonMain`, which carries the task dependency to
+ * every compilation, including the Kotlin/Native ones the XCFramework build links. Lint reads
+ * source directories straight off disk, so it is made to depend on the task explicitly, as in
+ * [KmpTestFixturesConventionPlugin].
+ *
+ * `EVENTS.md`, the catalogue as a readable page, is checked in next to `events.toml`.
+ * `writeAnalyticsEventsPage` rewrites it; `checkAnalyticsEventsPage` fails when it is stale.
+ */
+class AnalyticsCatalogueConventionPlugin : Plugin<Project> {
+    override fun apply(target: Project) {
+        with(target) {
+            val generateAnalyticsEvents = tasks.register<GenerateAnalyticsEvents>("generateAnalyticsEvents") {
+                catalogue.set(layout.projectDirectory.file("events.toml"))
+                outputDirectory.set(layout.buildDirectory.dir("generated/analytics/commonMain/kotlin"))
+            }
+
+            val catalogueFile = layout.projectDirectory.file("events.toml")
+            val pageFile = layout.projectDirectory.file("EVENTS.md")
+            tasks.register<WriteAnalyticsEventsPage>("writeAnalyticsEventsPage") {
+                catalogue.set(catalogueFile)
+                page.set(pageFile)
+            }
+            tasks.register<CheckAnalyticsEventsPage>("checkAnalyticsEventsPage") {
+                catalogue.set(catalogueFile)
+                page.set(pageFile)
+                fixCommand.set("./gradlew ${path.substringBeforeLast(':')}:writeAnalyticsEventsPage")
+            }
+
+            tasks.matching { it.name.startsWith("lint") || it.name.endsWith("LintModel") }
+                .configureEach { dependsOn(generateAnalyticsEvents) }
+
+            pluginManager.withPlugin("org.jetbrains.kotlin.multiplatform") {
+                extensions.configure<KotlinMultiplatformExtension> {
+                    sourceSets.named("commonMain") { kotlin.srcDir(generateAnalyticsEvents) }
+                }
+            }
+        }
+    }
+}

build-logic/convention/src/main/kotlin/com/getcode/buildlogic/analytics/AnalyticsCatalogue.kt

@@ -0,0 +1,12 @@
+package com.getcode.buildlogic.analytics
+
+/** Reads `events.toml` and writes the builders and value enums it describes, and `EVENTS.md`. */
+internal object AnalyticsCatalogue {
+    fun parse(text: String): Catalogue = CatalogueParser.parse(text)
+
+    /** The generated sources, keyed by path relative to the source root. */
+    fun emit(catalogue: Catalogue): Map<String, String> = KotlinEmitter.emit(catalogue)
+
+    /** `EVENTS.md`: the catalogue as a readable page. */
+    fun document(catalogue: Catalogue): String = MarkdownEmitter.emit(catalogue)
+}

build-logic/convention/src/main/kotlin/com/getcode/buildlogic/analytics/AnalyticsEventsPage.kt

@@ -0,0 +1,60 @@
+package com.getcode.buildlogic.analytics
+
+import org.gradle.api.DefaultTask
+import org.gradle.api.GradleException
+import org.gradle.api.file.RegularFileProperty
+import org.gradle.api.provider.Property
+import org.gradle.api.tasks.Input
+import org.gradle.api.tasks.InputFile
+import org.gradle.api.tasks.Internal
+import org.gradle.api.tasks.OutputFile
+import org.gradle.api.tasks.PathSensitive
+import org.gradle.api.tasks.PathSensitivity
+import org.gradle.api.tasks.TaskAction
+
+private fun page(catalogue: RegularFileProperty): String = try {
+    AnalyticsCatalogue.document(AnalyticsCatalogue.parse(catalogue.get().asFile.readText()))
+} catch (malformed: CatalogueException) {
+    throw GradleException(malformed.message.orEmpty(), malformed)
+}
+
+/** Writes `EVENTS.md` from `events.toml`. The page is checked in, so this writes into the module. */
+abstract class WriteAnalyticsEventsPage : DefaultTask() {
+
+    @get:InputFile
+    @get:PathSensitive(PathSensitivity.NONE)
+    abstract val catalogue: RegularFileProperty
+
+    @get:OutputFile
+    abstract val page: RegularFileProperty
+
+    @TaskAction
+    fun write() = page.get().asFile.writeText(page(catalogue))
+}
+
+/** Fails when the checked-in `EVENTS.md` is not what `events.toml` generates. */
+abstract class CheckAnalyticsEventsPage : DefaultTask() {
+
+    @get:InputFile
+    @get:PathSensitive(PathSensitivity.NONE)
+    abstract val catalogue: RegularFileProperty
+
+    /** Read only if it exists: a missing page is reported, not a missing-input failure. */
+    @get:Internal
+    abstract val page: RegularFileProperty
+
+    /** The command the failure tells the reader to run. */
+    @get:Input
+    abstract val fixCommand: Property<String>
+
+    @TaskAction
+    fun check() {
+        val file = page.get().asFile
+        val expected = page(catalogue)
+        if (!file.exists() || file.readText() != expected) {
+            throw GradleException(
+                "${file.name} is out of date with events.toml. Run `${fixCommand.get()}` and commit the result.",
+            )
+        }
+    }
+}

build-logic/convention/src/main/kotlin/com/getcode/buildlogic/analytics/Catalogue.kt

@@ -0,0 +1,64 @@
+package com.getcode.buildlogic.analytics
+
+/** The catalogue is malformed. The message names the entry at fault. */
+class CatalogueException(message: String) : IllegalArgumentException(message)
+
+/** `events.toml`, parsed and checked. Every reference in it resolves. */
+internal data class Catalogue(
+    val packageName: String,
+    val enums: List<EnumDef>,
+    val counters: List<EnumCase>,
+    val domains: List<Domain>,
+)
+
+/** A value list: a Kotlin enum whose cases carry the string sent to Mixpanel. */
+internal data class EnumDef(val name: String, val doc: String?, val cases: List<EnumCase>)
+
+internal data class EnumCase(val name: String, val value: String, val drift: String?)
+
+/** One generated `object`, e.g. `ChatEvents`, named from the [title] entries give, e.g. `Chat`. */
+internal data class Domain(val name: String, val title: String, val doc: String?, val builders: List<Builder>)
+
+internal data class Builder(
+    val name: String,
+    val event: Template,
+    val params: List<Param>,
+    val properties: List<Property>,
+    val doc: String?,
+    val drift: String?,
+)
+
+internal data class Param(val name: String, val type: ParamType, val nullable: Boolean) {
+    val kotlinType: String get() = type.kotlinName + if (nullable) "?" else ""
+}
+
+internal sealed class ParamType(val kotlinName: String) {
+    data object Text : ParamType("String")
+    data object Decimal : ParamType("Double")
+    data object Whole : ParamType("Long")
+    data object SmallWhole : ParamType("Int")
+    data object Flag : ParamType("Boolean")
+
+    /** The hand-written `Amount`, sent only through the `amount` group. */
+    data object Amount : ParamType("Amount")
+    data class Enum(val name: String) : ParamType(name)
+}
+
+internal sealed interface Property {
+    /** A parameter sent as it is, typed by the parameter. */
+    data class Value(val key: String, val param: Param) : Property
+
+    /** A text value built from literal text and parameters. */
+    data class Format(val key: String, val template: Template) : Property
+
+    /** The hand-written `amount(...)` block. */
+    data class AmountBlock(val param: Param) : Property
+}
+
+/** Text with `{param}` slots, used for event names and fixed-format values. */
+internal data class Template(val parts: List<Part>) {
+    sealed interface Part {
+        data class Literal(val text: String) : Part
+        data class Slot(val param: Param) : Part
+    }
+}