feat(analytics-events): make events.toml writable without Kotlin (#1547)

Author: bmc08gt

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

@@ -1,4 +1,6 @@
+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
@@ -21,6 +23,9 @@ import org.jetbrains.kotlin.gradle.dsl.KotlinMultiplatformExtension
  * 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) {
@@ -30,6 +35,18 @@ class AnalyticsCatalogueConventionPlugin : Plugin<Project> {
                 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) }
 

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

@@ -1,9 +1,12 @@
 package com.getcode.buildlogic.analytics
 
-/** Reads `events.toml` and writes the builders and value enums it describes. */
+/** 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

@@ -11,13 +11,13 @@ internal data class Catalogue(
     val domains: List<Domain>,
 )
 
-/** A value enum: a Kotlin enum whose cases carry the string sent to Mixpanel. */
+/** 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`. */
-internal data class Domain(val name: String, val doc: String?, val builders: List<Builder>)
+/** 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,