Enhance CI workflow with performance regression checks and AGP compatibility testing: add a new job to measure build performance for assembleDebug and ensure compatibility across multiple AGP versions. Update ci.yml to include performance checks and improve build stability. Remove obsolete refactor plan checklist document to streamline project documentation.

Author: efraespada

.github/workflows/ci.yml

@@ -29,3 +29,42 @@ jobs:
 
       - name: Sample app assembleDebug
         run: ./gradlew :app:assembleDebug --no-daemon
+
+      - name: Performance non-regression check (assembleDebug)
+        env:
+          PERF_MAX_SECONDS: "240"
+        run: |
+          ./gradlew :app:clean --no-daemon
+          ./gradlew :app:assembleDebug --no-daemon
+          start=$(date +%s)
+          ./gradlew :app:assembleDebug --no-daemon
+          end=$(date +%s)
+          elapsed=$((end - start))
+          echo "Measured assembleDebug (warm) time: ${elapsed}s"
+          if [ "$elapsed" -gt "$PERF_MAX_SECONDS" ]; then
+            echo "Performance regression: ${elapsed}s > ${PERF_MAX_SECONDS}s"
+            exit 1
+          fi
+
+  agp-compat:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        agp-version: ["8.0.2", "8.7.3", "9.0.0"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: 17
+
+      - name: Grant execute permission for gradlew
+        run: chmod +x gradlew
+
+      - name: Set AGP version in version catalog
+        run: sed -i.bak 's/^agp = ".*"/agp = "${{ matrix.agp-version }}"/' gradle/libs.versions.toml
+
+      - name: AGP compatibility check (assembleDebug)
+        run: ./gradlew :app:assembleDebug --no-daemon

docs/refactor-plan-checklist.md

@@ -1,9 +1,11 @@
 package dev.vyp.stringcare.plugin.domain.models
 
 import java.io.File
+import java.io.RandomAccessFile
 import java.nio.file.AtomicMoveNotSupportedException
 import java.nio.file.Files
 import java.nio.file.StandardCopyOption
+import java.security.MessageDigest
 
 /**
  * Copies [source] to [dest] via a temp file in the same directory, then replaces [dest].
@@ -13,24 +15,105 @@ internal fun copyToBackupAtomically(
     source: File,
     dest: File,
 ) {
-    dest.parentFile?.mkdirs()
-    val parent = dest.parentFile ?: error("Backup destination has no parent: ${dest.absolutePath}")
-    val tmp = File.createTempFile("sc-backup-", ".tmp", parent)
-    try {
-        Files.copy(source.toPath(), tmp.toPath(), StandardCopyOption.REPLACE_EXISTING)
+    withFileLock(dest) {
+        dest.parentFile?.mkdirs()
+        val parent = dest.parentFile ?: error("Backup destination has no parent: ${dest.absolutePath}")
+        val tmp = File.createTempFile("sc-backup-", ".tmp", parent)
         try {
-            Files.move(
-                tmp.toPath(),
-                dest.toPath(),
-                StandardCopyOption.ATOMIC_MOVE,
+            Files.copy(source.toPath(), tmp.toPath(), StandardCopyOption.REPLACE_EXISTING)
+            try {
+                Files.move(
+                    tmp.toPath(),
+                    dest.toPath(),
+                    StandardCopyOption.ATOMIC_MOVE,
+                    StandardCopyOption.REPLACE_EXISTING,
+                )
+            } catch (_: AtomicMoveNotSupportedException) {
+                Files.move(tmp.toPath(), dest.toPath(), StandardCopyOption.REPLACE_EXISTING)
+            }
+            val sourceChecksum = source.sha256Hex()
+            val backupChecksum = dest.sha256Hex()
+            check(sourceChecksum == backupChecksum) {
+                "Backup checksum mismatch for ${source.absolutePath} -> ${dest.absolutePath}"
+            }
+        } finally {
+            if (tmp.exists()) {
+                tmp.delete()
+            }
+        }
+    }
+}
+
+internal inline fun <T> withFileLock(
+    file: File,
+    action: () -> T,
+): T {
+    file.parentFile?.mkdirs()
+    if (!file.exists()) {
+        file.createNewFile()
+    }
+    RandomAccessFile(file, "rw").use { raf ->
+        raf.channel.use { channel ->
+            channel.lock().use {
+                return action()
+            }
+        }
+    }
+}
+
+internal inline fun <T> withBackup(
+    backupFile: File,
+    targetFile: File,
+    action: () -> T,
+): T {
+    return try {
+        action()
+    } catch (error: Throwable) {
+        withFileLock(targetFile) {
+            Files.copy(
+                backupFile.toPath(),
+                targetFile.toPath(),
                 StandardCopyOption.REPLACE_EXISTING,
             )
-        } catch (_: AtomicMoveNotSupportedException) {
-            Files.move(tmp.toPath(), dest.toPath(), StandardCopyOption.REPLACE_EXISTING)
         }
-    } finally {
-        if (tmp.exists()) {
-            tmp.delete()
+        throw error
+    }
+}
+
+/**
+ * Shared backup/rollback workflow for any [Backupable] item.
+ *
+ * Backups are created into [tempRoot], then [action] is executed for each item.
+ * If [action] fails for an item, that item is restored from its backup and the error is rethrown.
+ */
+internal inline fun <T : Backupable> forEachWithBackup(
+    items: Iterable<T>,
+    tempRoot: String,
+    action: (T) -> Unit,
+) {
+    items.forEach { item ->
+        val backup = item.backup(tempRoot)
+        val target =
+            when (item) {
+                is ResourceFile -> item.file
+                is AssetsFile -> item.file
+                else -> error("Unsupported Backupable type: ${item::class.qualifiedName}")
+            }
+        withBackup(backup, target) {
+            action(item)
+        }
+    }
+}
+
+private fun File.sha256Hex(): String {
+    val digest = MessageDigest.getInstance("SHA-256")
+    inputStream().use { stream ->
+        val buffer = ByteArray(DEFAULT_BUFFER_SIZE)
+        while (true) {
+            val read = stream.read(buffer)
+            if (read <= 0) break
+            digest.update(buffer, 0, read)
         }
     }
+    return digest.digest().joinToString(separator = "") { b -> "%02x".format(b) }
 }

plugin/src/main/kotlin/dev/vyp/stringcare/plugin/domain/models/BackupCopy.kt

@@ -2,11 +2,24 @@ package dev.vyp.stringcare.plugin.domain.models
 
 import java.io.File
 
+/**
+ * String XML resource file selected for obfuscation and backup.
+ *
+ * Example:
+ * `ResourceFile(File("src/main/res/values/strings.xml"), "src/main", "app")`
+ *
+ * @property file Physical file in the project.
+ * @property sourceFolder Source-set root used to rebuild relative backup paths.
+ * @property module Gradle module name that owns the resource file.
+ */
 data class ResourceFile(
     val file: File,
     val sourceFolder: String,
     val module: String,
 ) : Backupable {
+    /**
+     * Creates a backup copy of this resource file inside [tempRoot], preserving module/source relative path.
+     */
     override fun backup(tempRoot: String): File {
         val cleanPath =
             "$tempRoot${File.separator}$module${File.separator}$sourceFolder${file.absolutePath.split(sourceFolder)[1]}"

plugin/src/main/kotlin/dev/vyp/stringcare/plugin/domain/models/ResourceFile.kt

@@ -3,7 +3,15 @@ package dev.vyp.stringcare.plugin.domain.models
 /**
  * A `<string>` resource entry marked for obfuscation (`hidden` not false).
  *
+ * Example:
+ * `StringEntity("welcome_title", attributes, "Welcome", "string", 0, androidTreatment = true)`
+ *
+ * @param name XML `name` attribute.
+ * @param attributes Original XML attributes copied from the source node.
+ * @param value Current string value (plain text or obfuscated payload).
+ * @param tag XML tag name, usually `string`.
  * @param index DOM order index among all `<string>` nodes (used when rewriting XML).
+ * @param androidTreatment Whether Android-style whitespace treatment should be applied before obfuscation.
  */
 data class StringEntity(
     val name: String,

plugin/src/main/kotlin/dev/vyp/stringcare/plugin/domain/models/StringEntity.kt

@@ -8,12 +8,30 @@ import dev.vyp.stringcare.plugin.internal.Stark
  * @throws UnsatisfiedLinkError if native code is not loaded on this host.
  */
 class ObfuscationService {
+    /**
+     * Obfuscates a payload using the JNI runtime.
+     *
+     * @param key SHA-1 signing fingerprint used as obfuscation key.
+     * @param payload Raw bytes to obfuscate.
+     * @param applicationId Android application id mixed in native transformation.
+     * @return Obfuscated bytes to persist in resources/assets.
+     * @throws UnsatisfiedLinkError if native code is unavailable for this host.
+     */
     fun obfuscate(
         key: String,
         payload: ByteArray,
         applicationId: String,
     ): ByteArray = Stark.obfuscate(key, payload, applicationId)
 
+    /**
+     * Reverts bytes previously obfuscated by [obfuscate].
+     *
+     * @param key SHA-1 signing fingerprint used during obfuscation.
+     * @param payload Obfuscated bytes.
+     * @param applicationId Android application id used by native transformation.
+     * @return Plain decoded bytes.
+     * @throws UnsatisfiedLinkError if native code is unavailable for this host.
+     */
     fun reveal(
         key: String,
         payload: ByteArray,

plugin/src/main/kotlin/dev/vyp/stringcare/plugin/infrastructure/crypto/ObfuscationService.kt

@@ -5,6 +5,13 @@ import java.io.File
 
 /** Public entry for `strings.xml` parsing (SAX + optional DOM fallback). */
 object XmlParser {
+    /**
+     * Parses all obfuscatable string entries from [file].
+     *
+     * @param file XML file to parse.
+     * @param domFallback Parser to use when SAX cannot preserve nested markup semantics.
+     * @return Ordered list of obfuscatable [StringEntity] values.
+     */
     fun parse(
         file: File,
         domFallback: (File) -> List<StringEntity>,

plugin/src/main/kotlin/dev/vyp/stringcare/plugin/infrastructure/parsers/XmlParser.kt

@@ -0,0 +1,4 @@
+package dev.vyp.stringcare.plugin.internal
+
+@Suppress("NOTHING_TO_INLINE")
+inline fun ByteArray.toReadableString(): String = joinToString(separator = ", ") { it.toString() }