Nexus - AI Task Orchestrator

09-diagram-sync-check
Procedimiento: Diagram Sync Check

Documentacion
1 plugin(s)
Titulo
Descripcion
Contenido Markdown
11538 caracteres
# Procedimiento: Diagram Sync Check

## Metadata
- **ID**: PROC-09
- **Nombre**: Diagram Sync Check
- **Categor├¡a**: Gesti├│n y Documentaci├│n
- **Frecuencia**: Mensual
- **Duraci├│n estimada**: 20-30 minutos
- **Agente principal**: `documentation-architect`
- **Agentes de apoyo**: `dotnet-architect`
- **Skills requeridos**: `documentation-standards`, `architecture-patterns`
- **Actualizado**: 2025-01-07
- **Versi├│n**: 1.0

---

## Objetivo

Verificar que los diagramas de arquitectura y documentaci├│n visual (Mermaid, PlantUML, Draw.io) est├®n sincronizados con el c├│digo actual, detectando discrepancias entre la documentaci├│n visual y la implementaci├│n real.

---

## Alcance

### Tipos de Diagramas a Verificar
- **Mermaid**: `*.mermaid`, `*.mmd`, bloques ```mermaid en markdown
- **PlantUML**: `*.puml`, `*.plantuml`, `*.wsd`
- **Draw.io**: `*.drawio`, `*.drawio.svg`, `*.drawio.png`
- **SVG embebidos**: `*.svg` en carpetas docs/

### Elementos a Comparar
- Clases y sus relaciones
- M├®todos p├║blicos principales
- Endpoints de API
- Flujos de datos
- Componentes de arquitectura
- Integraciones externas

---

## Pre-requisitos

1. Acceso al repositorio del proyecto
2. Conocimiento de la estructura de carpetas
3. Herramientas de parsing (opcional): mermaid-cli, plantuml

---

## Procedimiento

### Paso 1: Inventariar Diagramas Existentes (5 min)

```bash
# Buscar todos los diagramas en el proyecto
find . -type f \( -name "*.mermaid" -o -name "*.mmd" -o -name "*.puml" -o -name "*.plantuml" -o -name "*.drawio" -o -name "*.drawio.svg" \) 2>/dev/null

# Buscar SVGs en carpetas de documentaci├│n
find ./docs -type f -name "*.svg" 2>/dev/null

# Buscar bloques mermaid en markdown
grep -r "```mermaid" --include="*.md" . 2>/dev/null | cut -d: -f1 | sort -u
```

**Registrar:**
- [ ] Total de diagramas encontrados: ___
- [ ] Ubicaciones principales: ___
- [ ] Tipos predominantes: ___

### Paso 2: Extraer Entidades del C├│digo (10 min)

#### Para proyectos .NET:
```bash
# Listar todas las clases p├║blicas
grep -rn "public class\|public interface\|public record\|public struct" --include="*.cs" src/ | grep -v "\.Designer\.cs\|\.g\.cs"

# Listar controllers y endpoints
grep -rn "\[HttpGet\|\[HttpPost\|\[HttpPut\|\[HttpDelete\|\[Route\|public class.*Controller" --include="*.cs" src/

# Listar servicios registrados
grep -rn "AddScoped\|AddSingleton\|AddTransient" --include="*.cs" src/
```

#### Para proyectos TypeScript/Node:
```bash
# Listar clases y exports principales
grep -rn "export class\|export interface\|export type\|export function" --include="*.ts" src/

# Listar endpoints en Express/NestJS
grep -rn "@Get\|@Post\|@Put\|@Delete\|router\.\(get\|post\|put\|delete\)" --include="*.ts" src/
```

**Registrar entidades clave del c├│digo:**
- [ ] Clases principales: ___
- [ ] Controllers/Endpoints: ___
- [ ] Servicios: ___

### Paso 3: Analizar Diagramas de Clases (5 min)

Para cada diagrama de clases encontrado:

1. **Extraer entidades del diagrama:**
   ```
   - Listar todas las clases/interfaces mencionadas
   - Listar relaciones (herencia, composici├│n, dependencia)
   - Listar m├®todos documentados
   ```

2. **Comparar con c├│digo:**
   - [ ] ┬┐Existen todas las clases del diagrama en el c├│digo?
   - [ ] ┬┐Hay clases en el c├│digo que faltan en el diagrama?
   - [ ] ┬┐Las relaciones son correctas?
   - [ ] ┬┐Los m├®todos principales est├ín documentados?

**Ejemplo de checklist para diagrama de clases:**
```markdown
Diagrama: docs/architecture/domain-model.mermaid
| Entidad en Diagrama | Existe en C├│digo | Estado |
|---------------------|------------------|--------|
| User                | src/Domain/User.cs | OK |
| OrderService        | NO ENCONTRADO    | DESACTUALIZADO |
| IRepository         | src/Core/IRepository.cs | OK |
```

### Paso 4: Analizar Diagramas de Arquitectura (5 min)

Para diagramas de componentes/arquitectura:

1. **Verificar componentes:**
   - [ ] ┬┐Todos los microservicios/m├│dulos existen?
   - [ ] ┬┐Las integraciones externas son actuales?
   - [ ] ┬┐Los flujos de datos son correctos?

2. **Verificar endpoints API:**
   ```
   - Comparar endpoints en diagrama vs controllers reales
   - Verificar m├®todos HTTP correctos
   - Verificar rutas actuales
   ```

**Ejemplo de verificaci├│n de endpoints:**
```markdown
Diagrama: docs/api/endpoints.svg
| Endpoint en Diagrama | Endpoint Real | Estado |
|---------------------|---------------|--------|
| GET /api/users      | UsersController.Get() | OK |
| POST /api/orders    | NO EXISTE     | ELIMINAR DEL DIAGRAMA |
| GET /api/products   | NO EN DIAGRAMA | AGREGAR |
```

### Paso 5: Generar Reporte de Discrepancias (5 min)

Crear lista de hallazgos:

```markdown
## Reporte de Sincronizaci├│n de Diagramas
**Fecha**: YYYY-MM-DD
**Proyecto**: [nombre]

### Resumen
- Diagramas analizados: X
- Sincronizados: Y
- Con discrepancias: Z

### Discrepancias Encontradas

#### Alta Prioridad (Arquitectura incorrecta)
1. [diagrama]: [descripci├│n del problema]
   - **Acci├│n**: [actualizar diagrama / actualizar c├│digo]

#### Media Prioridad (Elementos faltantes)
1. [diagrama]: [descripci├│n]
   - **Acci├│n**: [agregar elemento]

#### Baja Prioridad (Mejoras cosm├®ticas)
1. [diagrama]: [descripci├│n]
   - **Acci├│n**: [sugerencia]

### Elementos Obsoletos (Eliminar de diagramas)
- [lista de elementos que ya no existen]

### Elementos Nuevos (Agregar a diagramas)
- [lista de elementos del c├│digo sin documentar]
```

---

## Criterios de ├ëxito

| Criterio | Umbral OK | Umbral Warning | Umbral Critical |
|----------|-----------|----------------|-----------------|
| Diagramas sincronizados | >90% | 70-90% | <70% |
| Entidades faltantes | <5 | 5-15 | >15 |
| Endpoints desactualizados | 0 | 1-3 | >3 |
| Diagramas sin revisar | 0 | 1-2 | >2 |

---

## Automatizaci├│n

### Script de Verificaci├│n B├ísica

```powershell
# sync-diagrams-check.ps1
param(
    [string]$ProjectPath = ".",
    [string]$OutputPath = "./diagram-sync-report.md"
)

$diagramFiles = @()
$codeEntities = @()

# Buscar diagramas
$diagramFiles += Get-ChildItem -Path $ProjectPath -Recurse -Include "*.mermaid","*.mmd","*.puml","*.drawio" -ErrorAction SilentlyContinue

# Buscar clases en c├│digo .NET
$classMatches = Select-String -Path "$ProjectPath\src\**\*.cs" -Pattern "public (class|interface|record) (\w+)" -ErrorAction SilentlyContinue
$codeEntities = $classMatches | ForEach-Object { $_.Matches.Groups[2].Value } | Sort-Object -Unique

Write-Host "=== Diagram Sync Check ===" -ForegroundColor Cyan
Write-Host "Diagramas encontrados: $($diagramFiles.Count)"
Write-Host "Entidades en c├│digo: $($codeEntities.Count)"

# Exportar para an├ílisis manual
$report = @"
# Diagram Sync Check Report
**Fecha**: $(Get-Date -Format "yyyy-MM-dd HH:mm")
**Proyecto**: $ProjectPath

## Diagramas Encontrados
$($diagramFiles | ForEach-Object { "- $($_.FullName)" } | Out-String)

## Entidades en C├│digo
$($codeEntities | ForEach-Object { "- $_" } | Out-String)

## Siguiente Paso
Revisar manualmente cada diagrama contra las entidades listadas.
"@

$report | Out-File -FilePath $OutputPath -Encoding UTF8
Write-Host "Reporte generado: $OutputPath" -ForegroundColor Green
```

### Ejecuci├│n No-Interactiva

Para ejecuci├│n automatizada v├¡a MaintenanceWorker:

```yaml
# En project-config.yml
procedures:
  PROC-09:
    auto_mode: true
    output_format: "markdown"
    notify_on_discrepancies: true
    min_sync_threshold: 80  # Alertar si <80% sincronizado
```

---

## Integraci├│n con CI/CD

### GitHub Actions / GitLab CI

```yaml
diagram-sync-check:
  stage: documentation
  script:
    - pwsh ./scripts/sync-diagrams-check.ps1 -ProjectPath . -OutputPath ./artifacts/diagram-report.md
  artifacts:
    paths:
      - artifacts/diagram-report.md
  rules:
    - if: $CI_PIPELINE_SOURCE == "schedule"  # Solo en pipelines programados
```

---

## Herramientas Recomendadas

| Herramienta | Uso | Instalaci├│n |
|-------------|-----|-------------|
| **mermaid-cli** | Validar sintaxis Mermaid | `npm install -g @mermaid-js/mermaid-cli` |
| **plantuml** | Validar/renderizar PlantUML | `choco install plantuml` o jar |
| **c4builder** | Diagramas C4 | `npm install -g c4builder` |
| **structurizr** | Arquitectura as Code | Java-based |

---

## Mejores Pr├ícticas

1. **Mantener diagramas cerca del c├│digo**
   - `src/Module/docs/` mejor que `docs/` centralizado
   - Facilita actualizaci├│n junto con cambios de c├│digo

2. **Usar formatos de texto**
   - Preferir Mermaid/PlantUML sobre Draw.io
   - Se pueden versionar y revisar en PRs

3. **Automatizar generaci├│n cuando sea posible**
   - Generar diagramas de clases desde c├│digo
   - Generar diagramas de API desde OpenAPI/Swagger

4. **Documentar fecha de ├║ltima verificaci├│n**
   - Incluir metadatos en cada diagrama
   - `<!-- Verificado: 2025-01-07 por PROC-09 -->`

---

## Troubleshooting

| Problema | Causa | Soluci├│n |
|----------|-------|----------|
| Muchos falsos positivos | Diagramas de alto nivel vs c├│digo detallado | Ajustar nivel de detalle esperado |
| No encuentra diagramas | Extensiones no est├índar | Ampliar patrones de b├║squeda |
| Clases internas marcadas como faltantes | Incluye clases privadas | Filtrar solo p├║blicas |
| Diagrama binario (Draw.io) | No se puede parsear | Exportar a SVG/PNG con nombres descriptivos |

---


---

## Output Estructurado (Nexus)

Al finalizar, el agente DEBE generar un bloque JSON con el siguiente formato para que Nexus pueda procesarlo automaticamente:

```json
{
  "result": "success",
  "summary": "Ejecucion de PROC-09 completada. [Descripcion breve de resultados]",
  "metrics": {
    "issues_found": 0,
    "issues_resolved": 0,
    "score": 85, "drift_percent": 8,
    "custom": {
      "procedure_specific_metric": "value"
    }
  },
  "backlog_items": [
    {
      "title": "Titulo del item de seguimiento",
      "description": "Descripcion detallada si se requiere accion futura",
      "priority": "medium",
      "type": "improvement",
      "tags": ["proc-09"]
    }
  ],
  "next_steps": [
    "Accion recomendada 1",
    "Accion recomendada 2"
  ],
  "warnings": [
    "Advertencias encontradas durante la ejecucion"
  ]
}
```

**Campos requeridos:**
- `result`: `"success"` | `"partial"` | `"failed"`
- `summary`: Resumen ejecutivo en 1-3 lineas

**Metricas especificas de este procedure:**
- diagrams_checked, diagrams_outdated

**Criterios de resultado:**
- `success`: Procedimiento completado sin errores criticos
- `partial`: Completado con algunos problemas menores o items pendientes
- `failed`: Error critico o no se pudo completar

## Historial de Ejecuciones

| Fecha | Ejecutor | Diagramas | Discrepancias | Acciones |
|-------|----------|-----------|---------------|----------|
| YYYY-MM-DD | @usuario | X | Y | [link a PR] |

---

## Referencias

- [Mermaid Documentation](https://mermaid.js.org/)
- [PlantUML Guide](https://plantuml.com/)
- [C4 Model](https://c4model.com/)
- [Architecture Decision Records](https://adr.github.io/)

---

**ACCI├ôN REQUERIDA AL FINALIZAR:**

```bash
echo "====== PROC-09 TERMINADO [$(date +%H%M%S)] ======" && echo "RESULTADO: Diagramas verificados: X, Sincronizados: Y%, Discrepancias: Z"
```