data_drain 0.3.2 → 0.5.0

data/docs/execution/v0.5.0-OBSERVACIONES.md

@@ -0,0 +1,167 @@
+# Observaciones — v0.5.0
+
+Generado por: big-pickle
+Fecha: 2026-04-15
+Revisor: big-pickle (análisis de código real vs plan v2)
+
+---
+
+## Observación 1 — Breaking change implícito en `create_job`/`ensure_job`
+
+**Severidad:** Alta
+
+**Hallazgo:** El plan dice "Breaking: ninguno", pero la firma cambia:
+
+```ruby
+# ACTUAL (script_location: es keyword REQUIRED)
+def self.create_job(job_name, role_arn:, script_location:, ...)
+
+# PLAN (script_location: nil con default, role_arn: sigue required → SyntaxError)
+def self.create_job(job_name, role_arn:, script_location: nil, script_path: nil, ...)
+# required keyword argument cannot have a default value
+```
+
+**Fix requerido:** `role_arn:` también debe tener default `nil`. Esto es técnicamente un cambio de API (aunque todos los callers usan kwargs, así que no rompe en la práctica).
+
+**Estado:** Verificar en pre-flight checklist.
+
+---
+
+## Observación 2 — `s3_client` existe y usa credential chain
+
+**Severidad:** Confirmada OK
+
+**Verificado en** `lib/data_drain/storage/s3.rb:44-50`:
+
+```ruby
+def s3_client
+  Aws::S3::Client.new(
+    region: @config.aws_region,
+    access_key_id: @config.aws_access_key_id,
+    secret_access_key: @config.aws_secret_access_key
+  )
+end
+```
+
+El SDK acepta `nil` en las credenciales y resuelve via credential chain automáticamente. Plan OK.
+
+---
+
+## Observación 3 — `changed_fields` incluye comparación de `script_location`
+
+**Severidad:** Confirmada OK
+
+**Verificado en** `lib/data_drain/glue_runner.rb:174-175`:
+
+```ruby
+changed << :command if current.command.name != desired[:command_name] ||
+                       current.command.script_location != desired[:script_location]
+```
+
+El `script_location` se compara dentro de `:command`. Cuando `ensure_job` construya `desired[:script_location] = final_script` (resultado del upload), el diffing funcionará correctamente.
+
+---
+
+## Observación 4 — `Storage::Local#upload_file` requiere directorio manual
+
+**Severidad:** Media
+
+**Hallazgo:** No existe `Configuration#local_bucket`. El `bucket` en `Storage::Local#upload_file` es un directorio local pasado por el caller.
+
+**Plan OK:** el plan ya documenta esto en la firma del método. Confirmar en pre-flight checklist que el implementador lo sepa.
+
+---
+
+## Observación 5 — `resolve_script_location` es `private_class_method` pero llamado desde métodos públicos
+
+**Severidad:** Info
+
+**Hallazgo:** Ruby permite que métodos públicos de clase llamen `private_class_method`. No hay error. El plan está correcto. Solo documentar para claridad del implementador.
+
+---
+
+## Observación 6 — `spec/data_drain/storage/local_spec.rb` no existe
+
+**Severidad:** Media
+
+**Hallazgo:** El plan propone specs para `Storage::Local#upload_file` pero el archivo no existe. Hay que crearlo en la fase correspondiente.
+
+**Acción:** Crear `spec/data_drain/storage/local_spec.rb` con los specs del plan.
+
+---
+
+## Observación 7 — `spec/data_drain/glue_runner_spec.rb` tiene specs existentes de `create_job`/`ensure_job`
+
+**Severidad:** Info
+
+**Hallazgo:** Ya existen specs en `spec/data_drain/glue_runner_spec.rb:161+` para `create_job` y `ensure_job`. Los specs nuevos del plan deben ser adicionales a los existentes, no reemplazarlos. Verificar que los tests existentes sigan pasando.
+
+---
+
+## Observación 8 — Test de `storage_mode = :local` requiere `reset_adapter!`
+
+**Severidad:** Baja
+
+**Hallazgo:** El test "levanta ConfigurationError si storage_mode es :local" cambia `storage_mode` globalmente. Debe hacer `reset_adapter!` en el `after` block para no contaminar otros tests.
+
+**Plan OK:** el plan menciona esto, solo confirmar que se implemente correctamente.
+
+---
+
+## Observación 9 — Campo `bytes` en evento observabilidad
+
+**Severidad:** Baja
+
+**Hallazgo:** El plan usa `bytes` como nombre de campo en `glue_runner.script_uploaded`. Según Wispro-Observability-Spec v1, los contadores deben usar la palabra `count` en la key.
+
+**Alternativas:**
+- `byte_count` (más consistente con spec)
+- `file_size` (más semántico)
+
+**Decisión:** Mantener `bytes` por convención established en contexto AWS/S3 (donde `ContentLength` se reporta como `bytes`). Bajo riesgo.
+
+---
+
+## Observación 10 — `content_type: "text/x-python"` es explícito
+
+**Severidad:** Info
+
+**Verificado:** S3 infiere correctamente `text/x-python` para archivos `.py` si no se provee. El plan usa explícito para mayor predictibilidad. OK.
+
+---
+
+## Observación 11 — Concurrencia sin lock
+
+**Severidad:** Info
+
+**Documentado en** plan. `put_object` sobrescribe siempre. Scripts PySpark son pequeños, riesgo bajo. Items 38 y 39 definidos como follow-ups.
+
+---
+
+## Resumen para el implementador
+
+| # | Severidad | Acción |
+|---|-----------|--------|
+| 1 | Alta | Clarificar en plan que `role_arn:` también tiene default `nil` |
+| 2 | Confirmada OK | `s3_client` existe, credential chain OK |
+| 3 | Confirmada OK | `changed_fields` compara `script_location` |
+| 4 | Media | Documentar que Local requiere directorio destino manual |
+| 5 | Info | `private_class_method` permitido en Ruby de clase pública |
+| 6 | Media | Crear `spec/data_drain/storage/local_spec.rb` |
+| 7 | Info | Tests existentes de `create_job`/`ensure_job` no se tocan |
+| 8 | Baja | Test de `storage_mode = :local` con `reset_adapter!` |
+| 9 | Baja | Mantener `bytes` (convención AWS) |
+| 10 | Info | `content_type` explícito OK |
+| 11 | Info | Concurrencia documentada, items 38/39 follow-ups |
+
+---
+
+## Checklist de pre-implementación
+
+- [ ] Clarificar que `role_arn:` también tiene default `nil` en el plan
+- [ ] Verificar `s3_client` existe en `Storage::S3` ✅
+- [ ] Verificar `changed_fields` incluye `script_location` ✅
+- [ ] Confirmar que no hay `Configuration#local_bucket` existente
+- [ ] Crear `spec/data_drain/storage/local_spec.rb`
+- [ ] Ejecutar `bundle exec rspec` antes de empezar para tener baseline verde
+- [ ] Ejecutar `bundle exec rubocop` antes de empezar para tener baseline verde