data_drain 0.3.0 → 0.3.2

data/docs/execution/archive/v0.3.1-OBSERVACIONES.md

@@ -0,0 +1,146 @@
+# Análisis v0.3.1 — Observaciones para revisión (actualizado)
+
+## 1. Baseline real vs plan
+
+| Aspecto | Plan original estimaba | Realidad medida |
+|---------|----------------------|-----------------|
+| Ofensas RuboCop en `spec/` | ~48 | **37** (12 files) |
+| `COUNT(*)` en `lib/` | no cuantificado | **3** (engine.rb×2, file_ingestor.rb×1) |
+| `stub_const` en specs | 2 files (solo S3) | **2 files: S3 + GlueRunner** ← scope item 19 ampliado |
+| Coverage threshold | 80% | **80%** (real 97.49%) |
+| CI branch trigger | main | **master** (bug pre-existente) |
+| Matrix Ruby | 3.4.4 solo | **3.4.4 solo** |
+
+## 2. Desglose de 37 ofensas RuboCop en spec/
+
+```
+Metrics/BlockLength         29   ← describe/context blocks largos (NO auto-correct)
+Layout/LineLength            5   ← safe auto-correct
+Naming/VariableNumber        2   ← renombrar o config
+Style/MultilineBlockChain    1   ← auto-correct
+---
+Total                       37
+```
+
+**Nota:** Las 29 de BlockLength NO se reducen con auto-correct. Se resuelven con la exclusión en `.rubocop.yml`. El autocorrect solo arreglará ~6 de las 37 (LineLength + MultilineBlockChain).
+
+## 3. Duplicación `build_path` en Local y S3 (Item 13)
+
+Ambos tienen la misma lógica (local.rb lines 26-29, s3.rb lines 21-24). `Storage::Base` existe con la interfaz pero sin lógica compartida. La extracción a `Base#build_path_base` es trivial (~10 min).
+
+## 4. Decisiones tomadas (incorporadas al plan)
+
+1. **Ruby mínimo: `>= 3.2`** — Ruby 3.0/3.1 EOL. CI 3 versiones. Alineado con `TargetRubyVersion: 3.2`. BREAKING preventivo en CHANGELOG.
+2. **Postgres en CI: mocks suficientes** — Tests de Engine usan `instance_double(PG::Connection)` y `instance_double(PG::Result)`. NO se levanta Postgres como service container.
+3. **`rubocop-rspec`: descartado para v0.3.1** — Ampliaría scope. Documentado como ítem 25 post-roadmap.
+
+## 5. Issues del plan original (resolución)
+
+| # | Issue | Resolución |
+|---|-------|-----------|
+| 4.1 | `rubocop-rspec` opcional ambiguo | Descartado explícitamente (decisión 3) |
+| 4.2 | Items 14 y 17 con dependencia implícita en CI | **Fusionados en Fase 1** |
+| 4.3 | Workflow CI en `master` no `main` | Incluido como fix en Fase 1 |
+| 4.4 | DuckDB binary amd64-only | OK por ahora (runners amd64) |
+| 4.5 | Compatibilidad DuckDB + Ruby 3.2/3.3 | Verificación explícita en Fase 1.7 |
+| 4.6 | Postgres en CI | Decisión 2 resuelve (mocks) |
+
+## 6. Nuevos issues encontrados
+
+### 6.1 YAML de la matrix Ruby malformado (BUG)
+
+**Severidad:** Bug — impide ejecución
+
+El bloque YAML en Fase 1.5 tiene `steps:` anidado dentro de `strategy:`, que es inválido en GitHub Actions. Los `steps` deben estar al nivel del `job`, no dentro de `strategy`.
+
+```yaml
+# INCORRECTO (lo que dice el plan)
+strategy:
+  fail-fast: false
+  matrix:
+    ruby: ["3.2", "3.3", "3.4"]
+steps:  # ← esto está mal ubicado
+  - uses: actions/checkout@v4
+
+# CORRECTO
+strategy:
+  fail-fast: false
+  matrix:
+    ruby: ["3.2", "3.3", "3.4"]
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+```
+
+**Acción:** Reescribir correctamente al implementar. No bloquea el plan conceptual.
+
+### 6.2 Badge URL depende del nombre del workflow
+
+**Severidad:** Bajo — verificar al implementar
+
+El badge usa:
+```markdown
+[![CI](https://github.com/gedera/data_drain/actions/workflows/main.yml/badge.svg)]
+```
+
+Es correcto si el workflow se llama `main.yml`. Si se renombra a `ci.yml`, el badge rompe. **Acción:** Verificar el nombre real del archivo del workflow antes de agregar el badge.
+
+### 6.3 Estimado YARD puede ser bajo
+
+**Severidad:** Estimación — ajustar expectativa
+
+El plan dice 4-6h para item 12. Scope real:
+
+| Componente | Items a documentar |
+|------------|-------------------|
+| Configuration | ~21 (18 attrs + 3 métodos) |
+| Observability | 3 |
+| Observability::Timing | 2 |
+| Storage::Base/Local/S3 | ~12 |
+| Errors | 4-5 |
+| Record | 5 |
+| **Total** | **~47 items** |
+
+× 3-5 min por item = **5-8h** estimado.
+
+**Acción:** Esperar 5-8h, no 4-6h. El Plan B de dividir YARD en dos releases sigue siendo correcto si se extiende.
+
+### 6.4 Bundler cache no se usa en CI
+
+**Severidad:** Mejora opcional post-release
+
+El workflow actual tiene `bundler-cache: false`. Cada job baja todas las gems desde cero (~20-30s por job × 3 jobs = ~6min extra). Podría agregarse `bundler-cache: true` para bajar tiempos, pero **no está en scope de v0.3.1**. Documentar como follow-up opcional.
+
+### 6.5 Marcar items `[~]` en el roadmap antes de ejecutar
+
+**Severidad:** Práctica operativa
+
+Las convenciones de `IMPROVEMENT_PLAN.md` dicen que antes de empezar un item hay que marcarlo `[~]` (en progreso). Si el ejecutor es un agente, debe hacerlo para mantener la memoria del proyecto consistente.
+
+## 7. Observaciones menores (sin acción)
+
+- DuckDB binary necesario antes de `bundle install` — correcto, el gem compila la C extension
+- Cache rubocop (`~/.cache/rubocop_cache`) no entra en conflicto con el paso de DuckDB — correcto
+- Fase 1.7 "verificar localmente" contradice "confiar en CI si no hay Rubies" — es intencional y correcto
+- Commit granularity en Fase 1 flexible — correcto, pero considerar rebase interactivo al final si se separan
+
+## 8. Resumen de acciones
+
+| Prioridad | Acción |
+|-----------|--------|
+| **Bloqueante** | Reescribir YAML de matrix Ruby en Fase 1.5 |
+| **Verificar** | Nombre del workflow para el badge (Fase 2) |
+| **Expectativa** | Item 12 toma 5-8h, no 4-6h |
+| **Post-release** | Bundler cache como follow-up opcional |
+| **Conveniencia** | Marcar items `[~]` en roadmap antes de ejecutar |
+
+## 9. Evaluación final
+
+**El plan es ejecutable como está.** Las correcciones necesarias son menores:
+
+1. **Corrección material:** reescribir el YAML de la matrix Ruby
+2. **Ajuste de expectativa:** item 12 estimado 5-8h
+
+El resto son verificaciones o mejoras opcionales. Las dependencias están correctas, los checkpoints son claros, y los Plan B cubren los escenarios de bloqueo.