@qubiit/lmagent 2.5.0

package/rules/testing.md

@@ -0,0 +1,326 @@
+# LMAgent Testing Rules
+
+> **Tipo**: `rule` | **Versión**: 2.1 | **Actualización**: 2026-01
+
+## 📌 Quick Reference
+
+| Métrica | Mínimo |
+|---------|--------|
+| **Cobertura Total** | >= 80% |
+| **Lógica de Negocio** | >= 90% |
+| **APIs** | >= 85% |
+| **Unit tests** | Cada función pública |
+| **Integration tests** | Cada endpoint |
+| **E2E tests** | Flujos críticos |
+
+| Herramienta | Python | TypeScript |
+|-------------|--------|------------|
+| **Runner** | pytest | jest |
+| **Coverage** | pytest-cov | jest --coverage |
+| **Mocking** | respx, unittest.mock | msw, jest.mock |
+
+### 👥 Roles que usan esta regla
+`qa-engineer`, `backend-engineer`, `frontend-engineer`
+
+---
+
+Este documento define las reglas y estándares de testing del framework.
+
+## 📊 Objetivos de Cobertura
+
+| Tipo de Código | Cobertura Mínima |
+|----------------|------------------|
+| Lógica de negocio | 90% |
+| Endpoints API | 85% |
+| Componentes UI | 75% |
+| Utilidades | 80% |
+| **Total Proyecto** | **80%** |
+
+---
+
+## Estructura de Tests
+
+### Python
+
+```
+tests/
+├── unit/                 # Tests aislados
+│   ├── test_utils.py
+│   └── test_services.py
+├── integration/          # Tests con DB/APIs
+│   ├── test_users_api.py
+│   └── test_auth_flow.py
+├── e2e/                  # Tests end-to-end
+│   └── test_user_journey.py
+├── fixtures/             # Test data
+│   └── users.json
+└── conftest.py           # Fixtures compartidos
+```
+
+### TypeScript
+
+```
+src/
+├── __tests__/            # Unit tests
+│   └── utils.test.ts
+├── components/
+│   └── Button/
+│       ├── Button.tsx
+│       └── Button.test.tsx  # Co-located
+e2e/
+├── login.spec.ts         # Playwright
+└── checkout.spec.ts
+```
+
+---
+
+## Naming Conventions
+
+### Nombres de Tests
+
+```python
+# Formato: test_{what}_{condition}_{expected}
+def test_calculate_discount_with_percentage_returns_reduced_price():
+def test_create_user_with_duplicate_email_raises_conflict():
+def test_login_with_invalid_password_returns_401():
+```
+
+### Archivos de Test
+
+```
+# Python
+test_{module}.py
+
+# TypeScript  
+{Component}.test.tsx
+{module}.test.ts
+```
+
+---
+
+## Patrones de Testing
+
+### Arrange-Act-Assert (AAA)
+
+```python
+def test_user_creation():
+    # Arrange
+    user_data = {"email": "test@example.com", "name": "Test"}
+    
+    # Act
+    result = create_user(user_data)
+    
+    # Assert
+    assert result.email == "test@example.com"
+    assert result.id is not None
+```
+
+### Given-When-Then (BDD)
+
+```python
+def test_discount_application():
+    # Given a cart with items totaling $100
+    cart = Cart(total=Decimal("100"))
+    
+    # When a 20% discount is applied
+    cart.apply_discount(percentage=20)
+    
+    # Then the total should be $80
+    assert cart.total == Decimal("80")
+```
+
+---
+
+## Fixtures y Factories
+
+### pytest Fixtures
+
+```python
+# conftest.py
+@pytest.fixture
+def sample_user() -> User:
+    return User(
+        id=uuid4(),
+        email="test@example.com",
+        name="Test User"
+    )
+
+@pytest.fixture
+async def authenticated_client(client, sample_user):
+    token = create_access_token(sample_user)
+    client.headers["Authorization"] = f"Bearer {token}"
+    return client
+```
+
+### Factories
+
+```python
+# tests/factories.py
+import factory
+from faker import Faker
+
+fake = Faker()
+
+class UserFactory(factory.Factory):
+    class Meta:
+        model = User
+    
+    id = factory.LazyFunction(uuid4)
+    email = factory.LazyAttribute(lambda _: fake.email())
+    name = factory.LazyAttribute(lambda _: fake.name())
+    created_at = factory.LazyFunction(datetime.utcnow)
+```
+
+---
+
+## Mocking
+
+### Cuándo Mockear
+
+- ✅ APIs externas
+- ✅ Servicios de terceros
+- ✅ Operaciones de I/O costosas
+- ✅ Tiempo/fecha
+- ❌ La base de datos en integration tests
+- ❌ Código interno (salvo excepciones)
+
+### Python (unittest.mock)
+
+```python
+from unittest.mock import patch, AsyncMock
+
+@patch("app.services.email.send_email")
+async def test_user_registration_sends_email(mock_send):
+    mock_send.return_value = AsyncMock()
+    
+    await register_user({"email": "test@example.com"})
+    
+    mock_send.assert_called_once_with(
+        to="test@example.com",
+        subject="Welcome!"
+    )
+```
+
+### HTTP Mocking (respx)
+
+```python
+import respx
+import httpx
+
+@respx.mock
+async def test_external_api_call():
+    respx.get("https://api.external.com/data").mock(
+        return_value=httpx.Response(200, json={"key": "value"})
+    )
+    
+    result = await fetch_external_data()
+    
+    assert result["key"] == "value"
+```
+
+---
+
+## Testing Async Code
+
+```python
+import pytest
+
+@pytest.mark.asyncio
+async def test_async_function():
+    result = await async_operation()
+    assert result is not None
+```
+
+---
+
+## Testing Exceptions
+
+```python
+import pytest
+
+def test_invalid_input_raises_error():
+    with pytest.raises(ValueError, match="must be positive"):
+        calculate_price(-10)
+
+async def test_not_found_raises_404():
+    with pytest.raises(HTTPException) as exc_info:
+        await get_user("nonexistent")
+    
+    assert exc_info.value.status_code == 404
+```
+
+---
+
+## Test Performance
+
+### Markers para Tests Lentos
+
+```python
+@pytest.mark.slow
+def test_large_data_processing():
+    # Test que tarda más de 1 segundo
+    ...
+
+# pytest.ini
+[pytest]
+markers =
+    slow: marks tests as slow
+```
+
+### Ejecutar Excluyendo Lentos
+
+```bash
+pytest -m "not slow"
+```
+
+---
+
+## CI Integration
+
+```yaml
+# .github/workflows/test.yml
+test:
+  runs-on: ubuntu-latest
+  steps:
+    - uses: actions/checkout@v4
+    
+    - name: Run tests
+      run: pytest --cov=app --cov-report=xml
+    
+    - name: Upload coverage
+      uses: codecov/codecov-action@v4
+```
+
+---
+
+## Anti-Patterns a Evitar
+
+```markdown
+❌ Tests que dependen del orden de ejecución
+❌ Tests que acceden a estado global
+❌ Tests que no limpian después de ejecutar
+❌ Tests demasiado grandes (>30 líneas)
+❌ Tests sin assertions
+❌ Mockear todo (tests frágiles)
+❌ Tests que dependen de la hora real
+❌ Ignorar tests intermitentes
+```
+
+---
+
+## Checklist de Testing
+
+```markdown
+## Antes de Push
+- [ ] Tests unitarios para nueva lógica
+- [ ] Tests de integración para endpoints
+- [ ] Coverage no disminuyó
+- [ ] No hay tests skipped sin razón
+- [ ] Tests locales pasan
+
+## Para Bugs
+- [ ] Test que reproduce el bug (falla primero)
+- [ ] Fix implementado
+- [ ] Test ahora pasa
+- [ ] Otros tests no rompieron
+```

package/rules/workflow.md

@@ -0,0 +1,353 @@
+# Flujo de Trabajo - LMAgent
+
+> **Tipo**: `rule` | **Versión**: 2.1 | **Actualización**: 2026-01
+
+## 📌 Quick Reference
+
+| Paso | Acción |
+|------|--------|
+| 1. **Entender** | Leer AGENTS.md + reglas aplicables |
+| 2. **Clasificar** | Determinar Level (0-4) + skill(s) |
+| 3. **Planear** | (Level 2+) Crear `implementation_plan.md` + pedir aprobación |
+| 4. **Implementar** | Modelos → Repos → Services → Routers → Tests |
+| 5. **Validar** | `pytest` + `ruff check` + `ruff format` |
+| 6. **Documentar** | Actualizar docs si hay cambios de uso |
+
+### Escalado Automático
+- Auth/Security → Mínimo Level 2
+- Migración DB → Mínimo Level 3
+- Breaking change → Mínimo Level 3
+
+### 👥 Roles que usan esta regla
+`orchestrator`, `backend-engineer`, `frontend-engineer`, `qa-engineer`
+
+---
+
+Este documento define el flujo de trabajo estándar que los agentes deben seguir dentro de LMAgent.
+
+## Flujo General
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    FLUJO DE TRABAJO LMAGENT                      │
+└─────────────────────────────────────────────────────────────────┘
+
+    ┌──────────────────────────────────────────────────────────┐
+    │  1. ENTENDER                                              │
+    │  • Leer AGENTS.md y reglas aplicables                    │
+    │  • Entender el contexto y requisitos                     │
+    │  • Identificar sistemas y archivos afectados             │
+    └────────────────────────┬─────────────────────────────────┘
+                             │
+                             ▼
+    ┌──────────────────────────────────────────────────────────┐
+    │  2. CLASIFICAR                                            │
+    │  • Determinar nivel (0-4) según config/levels.yaml       │
+    │  • Identificar skill(s) a activar                        │
+    │  • Estimar tiempo y complejidad                          │
+    └────────────────────────┬─────────────────────────────────┘
+                             │
+              ┌──────────────┴──────────────┐
+              │                             │
+              ▼                             ▼
+    ┌─────────────────────┐     ┌─────────────────────────────┐
+    │  Level 0-1          │     │  Level 2-4                  │
+    │  • Implementar      │     │  • Crear plan/artefactos    │
+    │    directamente     │     │  • Pedir confirmación       │
+    │  • Sin plan formal  │     │    antes de implementar     │
+    └──────────┬──────────┘     └──────────────┬──────────────┘
+               │                                │
+               │                                ▼
+               │                 ┌─────────────────────────────┐
+               │                 │  3. PLANEAR                 │
+               │                 │  • Crear implementation_plan│
+               │                 │  • Listar archivos a tocar  │
+               │                 │  • Definir tests necesarios │
+               │                 │  • Pedir confirmación       │
+               │                 └──────────────┬──────────────┘
+               │                                │
+               └───────────────┬────────────────┘
+                               │
+                               ▼
+    ┌──────────────────────────────────────────────────────────┐
+    │  4. IMPLEMENTAR                                          │
+    │  • Hacer cambios en pequeños bloques                     │
+    │  • Seguir patrones de código establecidos                │
+    │  • Commits claros y atómicos                             │
+    └────────────────────────┬─────────────────────────────────┘
+                             │
+                             ▼
+    ┌──────────────────────────────────────────────────────────┐
+    │  5. VALIDAR                                              │
+    │  • Ejecutar tests existentes                             │
+    │  • Agregar tests para código nuevo                       │
+    │  • Verificar linting y formato                           │
+    │  • Probar manualmente si aplica                          │
+    └────────────────────────┬─────────────────────────────────┘
+                             │
+                             ▼
+    ┌──────────────────────────────────────────────────────────┐
+    │  6. DOCUMENTAR                                           │
+    │  • Actualizar README si hay cambios de uso               │
+    │  • Documentar APIs nuevas                                │
+    │  • Agregar comentarios donde sea necesario               │
+    │  • Actualizar changelog si aplica                        │
+    └──────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Paso 1: ENTENDER
+
+### Siempre leer primero:
+1. **AGENTS.md** - Marco de trabajo general
+2. **Reglas aplicables** en `rules/`
+3. **Skill(s) relevante(s)** en `skills/`
+
+### Preguntas clave:
+- ¿Cuál es el objetivo de negocio?
+- ¿Qué sistemas están involucrados?
+- ¿Hay dependencias o restricciones?
+- ¿Existen patrones similares en el código?
+
+### Acciones:
+```
+1. Buscar archivos relevantes (grep, find)
+2. Leer código existente relacionado
+3. Revisar tests existentes
+4. Identificar patrones usados
+```
+
+---
+
+## Paso 2: CLASIFICAR
+
+### Determinar Nivel
+
+| Señales | Nivel |
+|---------|-------|
+| Typo, formato, config menor | 0 - Trivial |
+| Bug fix simple, refactor local | 1 - Small |
+| Feature nuevo, integración simple | 2 - Medium |
+| Sistema nuevo, múltiples servicios | 3 - Complex |
+| Migración, seguridad, compliance | 4 - Enterprise |
+
+### Reglas de Escalado Automático
+
+Subir nivel si:
+- Afecta archivos de autenticación → mínimo Level 2
+- Es migración de DB → mínimo Level 3
+- Toca seguridad/encriptación → mínimo Level 3
+- Es breaking change → mínimo Level 3
+- Afecta producción → mínimo Level 2
+
+### Identificar Skill(s)
+
+```
+¿Diseño de sistema?        → architect (/arch)
+¿Implementación backend?   → backend-engineer (/dev)
+¿Frontend/UI?              → frontend-engineer (/front)
+¿Mobile?                   → mobile-engineer (/mobile)
+¿Automatización/n8n?       → automation-engineer (/auto)
+¿Agentes de IA?            → ai-agent-engineer (/agent)
+¿Tests?                    → qa-engineer (/qa)
+¿Seguridad?                → security-analyst (/sec)
+¿Performance?              → performance-engineer (/perf)
+¿No está claro?            → orchestrator (/orch)
+```
+
+---
+
+## Paso 3: PLANEAR (Level 2+)
+
+### Crear Artefactos según Nivel
+
+| Nivel | Artefactos Requeridos |
+|-------|----------------------|
+| 2 | implementation_plan.md |
+| 3 | implementation_plan.md, architecture.md, test_plan.md |
+| 4 | Todos los anteriores + security_review.md, rollback_plan.md |
+
+### Template: implementation_plan.md
+
+```markdown
+# Implementation Plan: [Título]
+
+## Objetivo
+[Descripción del cambio y su propósito]
+
+## Nivel de Complejidad
+Level [X] - [Nombre]
+
+## Archivos a Modificar
+- [ ] `path/to/file1.py` - [Descripción del cambio]
+- [ ] `path/to/file2.py` - [Descripción del cambio]
+
+## Archivos Nuevos
+- [ ] `path/to/new_file.py` - [Propósito]
+
+## Dependencias
+- [Dependencia 1]
+- [Dependencia 2]
+
+## Plan de Implementación
+1. [Paso 1]
+2. [Paso 2]
+3. [Paso 3]
+
+## Tests Necesarios
+- [ ] Test para [funcionalidad 1]
+- [ ] Test para [funcionalidad 2]
+
+## Rollback Plan (si aplica)
+[Cómo revertir si algo sale mal]
+
+## Checklist Pre-implementación
+- [ ] Reglas relevantes leídas
+- [ ] Skill(s) correcto(s) activado(s)
+- [ ] Plan revisado por humano (si Level 3+)
+```
+
+### Pedir Confirmación
+
+Para Level 2+, siempre pedir confirmación antes de implementar:
+
+```
+📋 Plan de implementación creado.
+
+Nivel: [X]
+Archivos afectados: [N]
+Tiempo estimado: [T]
+
+¿Procedo con la implementación? [Sí/No/Ajustar]
+```
+
+---
+
+## Paso 4: IMPLEMENTAR
+
+### Principios
+
+1. **Cambios pequeños**: Un concepto por commit
+2. **Seguir patrones**: Usar patrones existentes del proyecto
+3. **Código limpio**: Type hints, docstrings, sin código muerto
+4. **Logs apropiados**: Logging estructurado, no prints
+
+### Orden de Implementación
+
+```
+1. Modelos/Schemas (estructuras de datos)
+2. Repositories (acceso a datos)
+3. Services (lógica de negocio)
+4. Routers (endpoints API)
+5. Tests
+6. Documentación
+```
+
+### Commits
+
+Formato: `type(scope): descripción`
+
+Tipos:
+- `feat`: Nueva funcionalidad
+- `fix`: Corrección de bug
+- `refactor`: Refactorización
+- `docs`: Documentación
+- `test`: Tests
+- `chore`: Mantenimiento
+
+Ejemplos:
+```
+feat(users): add email verification endpoint
+fix(auth): handle expired tokens correctly
+refactor(services): extract validation logic
+docs(api): update user endpoints documentation
+test(users): add tests for email verification
+```
+
+---
+
+## Paso 5: VALIDAR
+
+### Checklist de Validación
+
+```bash
+# 1. Tests pasan
+pytest --cov=app --cov-fail-under=80
+
+# 2. Linting pasa
+ruff check .
+ruff format --check .
+
+# 3. Types check (si usa mypy)
+mypy app/
+
+# 4. Build pasa (Docker)
+docker build -t test .
+```
+
+### Si algo falla
+
+1. **Tests fallan**: Arreglar código o tests según corresponda
+2. **Linting falla**: Aplicar fixes automáticos (`ruff format .`)
+3. **Build falla**: Revisar dependencias y Dockerfile
+
+---
+
+## Paso 6: DOCUMENTAR
+
+### Qué documentar
+
+| Cambio | Documentación |
+|--------|---------------|
+| Nuevo endpoint | Docstring + OpenAPI schema |
+| Nuevo servicio | README del módulo |
+| Breaking change | CHANGELOG + migrations |
+| Configuración nueva | .env.example + docs |
+| Workflow n8n | Documentación en automations/ |
+
+### Dónde documentar
+
+```
+docs/
+├── api/              # Documentación de APIs
+├── architecture/     # Diagramas y ADRs
+├── deployment/       # Guías de deployment
+└── workflows/        # Documentación de automatizaciones
+```
+
+---
+
+## Casos Especiales
+
+### Bug de Producción
+1. Reproducir el bug localmente
+2. Escribir test que falla
+3. Implementar fix
+4. Verificar que test pasa
+5. Deploy urgente si es crítico
+
+### Refactor Grande
+1. Crear branch de feature
+2. Dividir en PRs pequeños
+3. Mantener backwards compatibility
+4. Feature flags si es necesario
+
+### Integración con n8n
+1. Diseñar webhook primero (contract)
+2. Implementar endpoint
+3. Documentar para n8n
+4. Probar con workflow de prueba
+
+---
+
+## Reglas de Oro
+
+1. 📖 **Siempre leer AGENTS.md primero**
+2. 🎯 **Clasificar correctamente el nivel**
+3. 📝 **Planear antes de implementar (Level 2+)**
+4. ✅ **Tests para todo código nuevo**
+5. 📐 **Seguir patrones existentes**
+6. 🔄 **Commits pequeños y descriptivos**
+7. 📚 **Documentar cambios significativos**
+8. ❓ **Si hay duda, preguntar**