build: Introduce API Gradle Convention Plugin

Likely only one consumer: `:api`, added to standardize .kts files

The API has separate requirements, but these are noise in the main
gradle.kts file.

Issue 20775

Assisted-by: Claude Opus 4.7 - full refactor

Author: david-allison

api/build.gradle.kts

@@ -2,29 +2,15 @@ import com.android.build.api.dsl.LibraryExtension
 import com.android.build.gradle.internal.tasks.factory.dependsOn
 
 plugins {
-    // Use `id` to avoid classpath conflicts. Versions are pinned by buildSrc/.
-    id("com.android.library")
+    id("ankidroid.android.api")
     id("maven-publish")
 }
 
 group = "com.ichi2.anki"
 version = "2.0.0"
 
-kotlin {
-    explicitApi()
-    compilerOptions {
-        // enable explicit api mode for additional checks related to the public api
-        // see https://kotlinlang.org/docs/whatsnew14.html#explicit-api-mode-for-library-authors
-        freeCompilerArgs.add("-Xexplicit-api=strict")
-    }
-}
-
 configure<LibraryExtension> {
     namespace = "com.ichi2.anki.api"
-    compileSdk =
-        libs.versions.compileSdk
-            .get()
-            .toInt()
 
     buildFeatures {
         buildConfig = true
@@ -56,11 +42,6 @@ configure<LibraryExtension> {
             proguardFiles(getDefaultProguardFile("proguard-android-optimize.txt"), "proguard-rules.pro")
         }
     }
-    compileOptions {
-        // API remains on VERSION_11 for compatibility
-        sourceCompatibility = JavaVersion.VERSION_11
-        targetCompatibility = JavaVersion.VERSION_11
-    }
 
     publishing {
         singleVariant("release") {
@@ -70,8 +51,6 @@ configure<LibraryExtension> {
     }
 }
 
-apply(from = "../lint.gradle")
-
 dependencies {
     implementation(libs.androidx.annotation)
     implementation(libs.kotlin.stdlib)

buildSrc/src/main/kotlin/ankidroid.android.api.gradle.kts

@@ -0,0 +1,55 @@
+/*
+ *  Copyright (c) 2026 David Allison <davidallisongithub@gmail.com>
+ *
+ *  This program is free software; you can redistribute it and/or modify it under
+ *  the terms of the GNU General Public License as published by the Free Software
+ *  Foundation; either version 3 of the License, or (at your option) any later
+ *  version.
+ *
+ *  This program is distributed in the hope that it will be useful, but WITHOUT ANY
+ *  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+ *  PARTICULAR PURPOSE. See the GNU General Public License for more details.
+ *
+ *  You should have received a copy of the GNU General Public License along with
+ *  this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+// Convention plugin: Android library published as a public API artifact.
+//
+// Distinct from ankidroid.android-library:
+//   * Java source/target compat is 11 (not 17) for consumer compatibility.
+//   * Kotlin explicit-API strict mode is enabled (library-author quality check).
+//   * minSdk is not set.
+//
+// Publishing (maven-publish, singleVariant setup, POM metadata) is left to
+// the consuming module — it's intrinsically per-module configuration.
+
+import com.android.build.api.dsl.LibraryExtension
+import com.ichi2.anki.gradle.libsVersionFor
+import org.jetbrains.kotlin.gradle.dsl.KotlinAndroidProjectExtension
+
+plugins {
+    id("com.android.library")
+}
+
+extensions.configure<LibraryExtension> {
+    compileSdk = libsVersionFor("compileSdk").toInt()
+
+    compileOptions {
+        // API remains on VERSION_11 for consumer compatibility.
+        sourceCompatibility = JavaVersion.VERSION_11
+        targetCompatibility = JavaVersion.VERSION_11
+    }
+}
+
+extensions.configure<KotlinAndroidProjectExtension> {
+    explicitApi()
+    compilerOptions {
+        // Stricter checks on public API shape for library authors.
+        // See https://kotlinlang.org/docs/whatsnew14.html#explicit-api-mode-for-library-authors
+        freeCompilerArgs.add("-Xexplicit-api=strict")
+    }
+}
+
+// Shared project-wide lint configuration.
+apply(from = "${rootDir}/lint.gradle")

buildSrc/src/main/kotlin/ankidroid.android.library.gradle.kts

@@ -22,23 +22,17 @@
  */
 
 import com.android.build.api.dsl.LibraryExtension
-import org.gradle.api.artifacts.VersionCatalogsExtension
+import com.ichi2.anki.gradle.libsVersionFor
 
 plugins {
     id("com.android.library")
 }
 
-// Type-safe `libs` accessors aren't available in precompiled script plugins,
-// so read versions from the catalog explicitly.
-val libs = extensions.getByType<VersionCatalogsExtension>().named("libs")
-fun versionInt(alias: String): Int =
-    libs.findVersion(alias).get().requiredVersion.toInt()
-
 extensions.configure<LibraryExtension> {
-    compileSdk = versionInt("compileSdk")
+    compileSdk = libsVersionFor("compileSdk").toInt()
 
     defaultConfig {
-        minSdk = versionInt("minSdk")
+        minSdk = libsVersionFor("minSdk").toInt()
     }
 
     compileOptions {

buildSrc/src/main/kotlin/com/ichi2/anki/gradle/VersionCatalogs.kt

@@ -0,0 +1,38 @@
+/*
+ *  Copyright (c) 2026 David Allison <davidallisongithub@gmail.com>
+ *
+ *  This program is free software; you can redistribute it and/or modify it under
+ *  the terms of the GNU General Public License as published by the Free Software
+ *  Foundation; either version 3 of the License, or (at your option) any later
+ *  version.
+ *
+ *  This program is distributed in the hope that it will be useful, but WITHOUT ANY
+ *  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+ *  PARTICULAR PURPOSE. See the GNU General Public License for more details.
+ *
+ *  You should have received a copy of the GNU General Public License along with
+ *  this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+package com.ichi2.anki.gradle
+
+import org.gradle.api.Project
+import org.gradle.api.artifacts.VersionCatalog
+import org.gradle.api.artifacts.VersionCatalogsExtension
+import org.gradle.kotlin.dsl.getByType
+
+// Type-safe `libs` accessors aren't available in precompiled script plugins,
+// so read versions from the `libs` catalog explicitly.
+
+@Volatile
+private var cachedLibs: VersionCatalog? = null
+
+// A Project reference is required, so this can't be `by lazy { }`
+private fun Project.libs(): VersionCatalog =
+    cachedLibs ?: extensions
+        .getByType<VersionCatalogsExtension>()
+        .named("libs")
+        .also { cachedLibs = it }
+
+fun Project.libsVersionFor(alias: String): String =
+    libs().findVersion(alias).get().requiredVersion