Refactor StringCare plugin architecture and enhance functionality: migrate domain models to domain.models, streamline execution result handling with structured responses, and improve XML parsing with SAX-first approach. Update CI workflow to include coverage verification and enhance README.md with refactor plan checklist. Remove obsolete model classes and improve task management for better performance and clarity.

Author: efraespada

.github/workflows/ci.yml

@@ -21,7 +21,7 @@ jobs:
         run: chmod +x gradlew
 
       - name: Plugin unit tests
-        run: ./gradlew :plugin:test :plugin:jacocoTestReport :plugin:detekt --no-daemon
+        run: ./gradlew :plugin:test :plugin:jacocoTestReport :plugin:jacocoTestCoverageVerification :plugin:detekt --no-daemon
 
       - name: Plugin integration tests (optional)
         continue-on-error: true

.github/workflows/publish.yml

@@ -0,0 +1,30 @@
+# Manual / tag-driven publish to Maven Central (requires signing + Nexus credentials).
+name: Publish
+
+on:
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: "If true, only build plugin (no upload)"
+        required: false
+        default: "true"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    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: Build plugin JAR
+        run: ./gradlew :plugin:jar --no-daemon
+
+      # Wire signing + publish when secrets are configured:
+      # ./gradlew :plugin:publishPluginPublicationToSonatypeRepository -PnexusUsername=... -PnexusPassword=...

CHANGELOG.md

@@ -2,14 +2,34 @@
 
 ## [Unreleased] — refactor / 6.x groundwork
 
+### Added
+
+- **Docs**: [Refactor plan checklist](docs/refactor-plan-checklist.md) — seguimiento hecho/pendiente del roadmap del plugin.
+
 ### Changed
 
+- **Architecture**: Domain models under `domain.models` (with `models` typealiases for compatibility); `infrastructure` packages for parsers, Gradle wiring, crypto, filesystem; thin `ObfuscateStringsUseCase` + `ResourceRepository`.
+- **XML**: SAX-first `strings.xml` parsing with DOM fallback for nested markup; `XmlAttributes` / `XmlParser` facade.
+- **Tasks**: Gradle `Property` inputs on obfuscate/restore/preview tasks; `@DisableCachingByDefault` (sources are mutated in place — not suitable for `@CacheableTask`).
+- **AGP**: `compileOnly` for the Android Gradle Plugin dependency (provided at runtime on Android projects).
+- **JAR size**: With `compileOnly` AGP, plugin JAR is ~180KB vs previous multi‑MB fat jar (verify locally with `./gradlew :plugin:jar`).
 - **Gradle**: `StringCareBuildService` (shared build service) replaces mutable static state on `StringCarePlugin` for paths, temp dir, and variant applicationIds.
 - **Dependencies**: Removed Guava and Gson; added `kotlinx-serialization-json` for task JSON list inputs.
-- **Execution**: Shell commands use `ProcessBuilder` with a 60s timeout and structured `ExecutionResult` (`Success` / `Failure`).
+- **Execution**: Shell commands use `ProcessBuilder` with a 60s timeout and structured `ExecutionResult` (`Success` / `Failure` / `Timeout`).
 - **Native host libs**: SHA-256 verification before `System.load`, retries, optional verbose logging tied to `debug` in tasks.
 - **XML / scan**: Faster attribute iteration in `parseXML`; `walkTopDown` skips `build/`, `.gradle/`, `.git/`, `node_modules/`; `mapNotNull` for resource/asset discovery; idempotent `StringCareConfiguration.normalize()`.
 - **Tooling**: Detekt + baseline, ktlint (non-failing), JaCoCo hook, Develocity build scan terms in root `settings.gradle.kts`.
+- **Backups**: Resource/asset backups use temp-file copy + atomic move when the filesystem supports it.
+- **Tests**: `ObfuscationServiceTest` (JNI roundtrip when loaded), `BackupServiceTest`, UTF-16 / malformed XML parser cases; CI runs `jacocoTestCoverageVerification` with a low interim line threshold.
+
+### Breaking changes
+
+- **Internal APIs**: Static mutable state on `StringCarePlugin` (paths, temp folder, variant map) was removed in favor of `StringCareBuildService`. Any build logic or tests reaching into those internals must use task inputs / the registered build service instead.
+- **Dependencies on the plugin JAR**: Guava and Gson are no longer bundled; list-style DSL fields are serialized with Kotlin serialization in task properties. Pure-Java consumers of internal packages are unsupported.
+
+### Performance (roadmap vs previous generations)
+
+- XML handling targets **SAX-first** parsing with DOM only when nested `<string>` markup requires it, and filesystem walks **prune** heavy directories (`build/`, `.gradle/`, `.git/`, `node_modules/`). End-to-end timings depend on project size; run `./gradlew :plugin:test` and your app’s obfuscation tasks locally to validate.
 
 ### Migration notes
 

docs/README.md

@@ -13,6 +13,7 @@ StringCare Android provides **compile-time obfuscation** for strings and assets
 - [Publishing](publishing.md) — Release workflow, secrets, and local publish (`publishToMavenLocal`).
 - [Migration](migration.md) — Upgrading from 4.x to 5.0 (groupId, plugin ID, package, Gradle/AGP).
 - [Architecture](architecture.md) — Mono-repo layout, library vs plugin, JNI, and Variant API.
+- [Refactor plan checklist](refactor-plan-checklist.md) — Estado del roadmap de refactor del plugin (hecho vs pendiente).
 - [Contributing](contributing.md) — Release workflow secrets and local publish steps.
 - [Troubleshooting](troubleshooting.md) — Submodule, signing, plugin not found, publish job, JNI/NDK.
 - [Verify obfuscation](verify-obfuscation.md) — Comandos `gradlew` para comprobar que strings/assets se ofuscan (nativas del host, `syncPluginNativeLibraries`).

docs/refactor-plan-checklist.md

@@ -0,0 +1,119 @@
+# Refactor plan checklist (plugin / repo)
+
+Estado al **2026-03-19**. Marca lo implementado en el código actual; úsalo para seguimiento del roadmap.
+
+Leyenda: **`[x]`** hecho · **`[ ]`** pendiente / parcial · **`[~]`** hecho con matices (ver nota)
+
+---
+
+## Fase 0 — Setup y calidad base
+
+- [x] Rama / flujo de trabajo acordado para cambios grandes del plugin
+- [x] Detekt en `plugin/build.gradle.kts` + `config/detekt/detekt.yml` + **baseline** (`baseline.xml`)
+- [x] Ktlint en el plugin (`ignoreFailures`, exclusión legacy `Vars.kt`)
+- [x] Develocity / build scan en `settings.gradle.kts` (publicación condicional a fallos)
+- [x] Tests JUnit 5 por defecto; tarea `:plugin:integrationTest` + `@Tag("integration")` para clones/nested Gradle
+
+---
+
+## Fase 1 — Seguridad y ejecución
+
+- [x] Estado mutable del plugin migrado a **`StringCareBuildService`** + `StringCareSession` solo para tests
+- [x] Tareas críticas con **`usesService`** al build service
+- [x] Comandos shell vía **`ProcessBuilder`** (no shell inseguro directo en el path feliz)
+- [x] Timeout (~60s) y **`ExecutionResult.Timeout`**
+- [x] JNI del host: verificación **SHA-256** antes de cargar, reintentos, **`LoadResult`**, limpieza de temporales JNI (sin `deleteOnExit` como única estrategia)
+
+---
+
+## Fase 2 — Rendimiento y XML
+
+- [x] Parser **SAX-first** para `strings.xml` + **fallback DOM** si hay anidamiento / detector falla
+- [x] Fachada `XmlParser` / `StringsXmlParser`; `XParser` delega
+- [x] Walk de recursos con **prune** de `build/`, `.gradle/`, `.git/`, `node_modules/`
+- [x] `StringCareConfiguration.normalize()` idempotente
+- [x] Copia de backup **temp + move atómico** (`BackupCopy` + `ResourceFile` / `AssetsFile`)
+- [ ] Módulo **JMH** u otro benchmark reproducible para el parser
+- [ ] Regresión de rendimiento automatizada en CI
+
+---
+
+## Fase 3 — APIs Gradle
+
+- [x] Entradas de tareas como **`Property<>`** donde aplica
+- [x] **`@DisableCachingByDefault`** en tareas que mutan el árbol de fuentes (no `@CacheableTask`)
+- [x] Wiring con AGP: dependencias de merge/process/assets dentro de `onVariants {}` usando `tasks.matching { it.name == ... }.configureEach { ... }` (sin `afterEvaluate` ni `findByName`)
+- [x] Sustituido `afterEvaluate` por wiring lazy y seguro por nombre de tarea
+- [ ] Declarar **`@InputFiles` / outputs** fiables para tareas mutadoras (difícil mientras se editan fuentes in-place)
+
+---
+
+## Fase 4 — Arquitectura (capas)
+
+- [x] Modelos en `domain.models` (`StringEntity`, `ResourceFile`, `AssetsFile`, `ExecutionResult`, `Backupable`, etc.)
+- [x] `infrastructure`: parsers, filesystem (`BackupService`), crypto (`ObfuscationService`), Gradle (`FileSystemResourceRepository`)
+- [x] Casos de uso / repositorios (`ObfuscateStringsUseCase`, `ResourceRepository`)
+- [x] AGP como **`compileOnly`** en el plugin
+- [x] JSON de listas con **kotlinx-serialization** (sin Gson)
+- [x] **`ExtractFingerprintUseCase`** en `domain.usecases` (tests pueden llamar `extract` con `log` por defecto; `extractFingerprint` delega desde `internal`)
+- [ ] Partir **`Extensions.kt`** en módulos más pequeños (Gradle vs FS vs XML)
+
+---
+
+## Fase 5 — Kotlin y robustez
+
+- [x] Reducción de **`!!`** en fuentes principales del plugin (revisar periódicamente)
+- [x] Utilidades tipo `toReadableString` donde aplica
+- [~] API de ejecución: ahora **`execute(command: String)` → `Result<ExecutionResult>`** y existe overload con **`List<String>`**; queda como deuda dejar `List<String>` como API única
+
+---
+
+## Fase 6 — Tests y cobertura
+
+- [x] Tests unitarios por defecto **sin** integración pesada (`:plugin:test` excluye tag `integration`)
+- [x] JaCoCo: `jacocoTestReport` + **`jacocoTestCoverageVerification`** (umbral **bajo interino** ~12% líneas; objetivo roadmap **>80%**)
+- [x] Tests de infraestructura XML (`XmlParserInfrastructureTest`: SAX, DOM implícito, **UTF-16**, XML mal formado)
+- [x] `ObfuscationServiceTest` (roundtrip JNI con **`assumeTrue(Stark.isNativeLibLoaded() is LoadResult.Loaded)`)**
+- [x] `BackupServiceTest` vía `BackupService` + `defaultConfig()`
+- [x] Otros tests de configuración / JSON / fingerprint según el árbol actual (`ConfigurationNormalizationTest`, `FingerprintExtractionTest`, `JsonListsTest`, etc.)
+- [ ] Fixtures **`test-projects/`** minimalistas adicionales (además de samples existentes)
+- [ ] Cobertura **>80%** como gate duro en CI
+
+---
+
+## Fase 7 — Mantenibilidad
+
+- [x] Detekt con baseline (no “cero issues” sin baseline)
+- [ ] Subir poco a poco reglas / reducir baseline hasta acercarse a **Detekt sin baseline**
+- [x] Ktlint operativo; fallos no bloquean build (`ignoreFailures`)
+- [~] KDoc: presente en puntos clave; ampliar en APIs públicas internas del plugin
+
+---
+
+## Fase 8 — Documentación y CI/CD
+
+- [x] `CHANGELOG.md` actualizado con hitos del refactor
+- [x] `MIGRATION.md` / docs de migración
+- [x] `SECURITY.md` y documentación de contribución / build
+- [x] `plugin/README.md` (requisitos, DSL avanzado, troubleshooting, rendimiento)
+- [x] **`.github/workflows/ci.yml`**: test, JaCoCo report + **verification**, detekt, integration opcional, `assembleDebug`
+- [x] **`.github/workflows/publish.yml`**: esqueleto (build JAR; publicación manual documentada)
+- [ ] **OWASP Dependency-Check** (o equivalente) en Gradle y/o CI del plugin
+- [ ] **Matriz CI** (p.ej. varias versiones AGP / Gradle) donde tenga sentido para el composite build
+
+---
+
+## Resumen rápido
+
+| Área              | Estado |
+|-------------------|--------|
+| BuildService / JNI / ProcessBuilder | Listo |
+| XML SAX + DOM     | Listo |
+| Backup atómico    | Listo (sin locks ni dirs UUID dedicados) |
+| AGP wiring        | Estable con `onVariants` + `tasks.matching(...).configureEach` |
+| Tests + JaCoCo    | Listo con umbral bajo; subir cobertura |
+| OWASP / JMH / matriz AGP | Pendiente |
+
+---
+
+*Si el plan original vive fuera del repo (p.ej. adjunto en Cursor), copia aquí los IDs `phase-*` y alinéalos con las secciones anteriores.*

plugin/README.md

@@ -16,6 +16,39 @@ See repo root [CHANGELOG.md](../CHANGELOG.md), [MIGRATION.md](../MIGRATION.md),
 - Default `./gradlew :plugin:test` excludes `@Tag("integration")` (network + `git clone` KotlinSample + nested Gradle).
 - Full suite: `./gradlew :plugin:integrationTest` (may fail offline or if the sample repo changes).
 
+### Advanced configuration
+
+Apply in the **app** module `build.gradle.kts`:
+
+```kotlin
+plugins {
+    id("com.android.application")
+    id("dev.vyp.stringcare.plugin")
+}
+
+stringcare {
+    debug = false
+    skip = false
+    mockedFingerprint = "" // optional: offline / CI
+    srcFolders.add("src/main")
+    stringFiles.add("strings.xml")
+    assetsFiles.add("*.json")
+}
+```
+
+### Troubleshooting
+
+| Symptom | What to try |
+|--------|-------------|
+| `native library not available` | Run on a supported host/OS; ensure JNI prebuilts are packaged (see `preparePluginNativeLibraries`). |
+| Wrong or empty signing SHA1 | Run `./gradlew signingReport` for the same variant; check `mockedFingerprint` if offline. |
+| Tasks not ordered | Ensure `com.android.application` is applied before StringCare; use AGP 8.7+. |
+
+### Performance tuning
+
+- **Large projects**: SAX parsing is used for flat `<string>` entries; nested HTML strings fall back to DOM for that file.
+- **CI**: Use `./gradlew :plugin:test` (fast); defer `:plugin:integrationTest` to nightly or manual runs.
+- **Configuration cache**: Enabled at the root build; run `./gradlew :app:assembleDebug --configuration-cache` to validate.
 
 License
 -------

plugin/build.gradle.kts

@@ -38,7 +38,7 @@ repositories {
 
 dependencies {
     implementation(gradleApi())
-    implementation("com.android.tools.build:gradle:8.7.3")
+    compileOnly("com.android.tools.build:gradle:8.7.3")
     implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.3")
     testImplementation("org.junit.jupiter:junit-jupiter:5.11.0")
     testImplementation("org.mockito.kotlin:mockito-kotlin:5.4.0")
@@ -89,6 +89,20 @@ tasks.jacocoTestReport {
     }
 }
 
+/** Soft gate: raise minimum over time (target >80% per roadmap). */
+tasks.jacocoTestCoverageVerification {
+    dependsOn(tasks.test)
+    violationRules {
+        rule {
+            limit {
+                counter = "LINE"
+                value = "COVEREDRATIO"
+                minimum = "0.12".toBigDecimal()
+            }
+        }
+    }
+}
+
 detekt {
     buildUponDefaultConfig = true
     allRules = false
@@ -102,6 +116,7 @@ ktlint {
     ignoreFailures.set(true)
     filter {
         exclude("**/build/**")
+        exclude("**/Vars.kt")
     }
 }
 

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

@@ -0,0 +1,18 @@
+package dev.vyp.stringcare.plugin.domain.models
+
+import java.io.File
+
+data class AssetsFile(
+    val file: File,
+    val sourceFolder: String,
+    val module: String,
+) : Backupable {
+    override fun backup(tempRoot: String): File {
+        val cleanPath =
+            "$tempRoot${File.separator}$module${File.separator}$sourceFolder${file.absolutePath.split(sourceFolder)[1]}"
+                .replace("${File.separator}${File.separator}", File.separator)
+        val backupFile = File(cleanPath)
+        copyToBackupAtomically(file, backupFile)
+        return backupFile
+    }
+}

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

@@ -0,0 +1,36 @@
+package dev.vyp.stringcare.plugin.domain.models
+
+import java.io.File
+import java.nio.file.AtomicMoveNotSupportedException
+import java.nio.file.Files
+import java.nio.file.StandardCopyOption
+
+/**
+ * Copies [source] to [dest] via a temp file in the same directory, then replaces [dest].
+ * Uses [StandardCopyOption.ATOMIC_MOVE] when supported so readers rarely see a half-written file.
+ */
+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)
+        try {
+            Files.move(
+                tmp.toPath(),
+                dest.toPath(),
+                StandardCopyOption.ATOMIC_MOVE,
+                StandardCopyOption.REPLACE_EXISTING,
+            )
+        } catch (_: AtomicMoveNotSupportedException) {
+            Files.move(tmp.toPath(), dest.toPath(), StandardCopyOption.REPLACE_EXISTING)
+        }
+    } finally {
+        if (tmp.exists()) {
+            tmp.delete()
+        }
+    }
+}

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

@@ -0,0 +1,8 @@
+package dev.vyp.stringcare.plugin.domain.models
+
+import java.io.File
+
+/** Filesystem types that support backup into a StringCare temp root. */
+fun interface Backupable {
+    fun backup(tempRoot: String): File
+}