Nexus - AI Task Orchestrator

08-documentation-links-validator
Procedimiento: Validaci├│n de Enlaces en Documentaci├│n

Documentacion
1 plugin(s)
Titulo
Descripcion
Contenido Markdown
8211 caracteres
# Procedimiento: Validaci├│n de Enlaces en Documentaci├│n

## Metadata
- **ID**: PROC-08
- **Frecuencia**: Semanal
- **Duraci├│n estimada**: 10-20 min
- **Requiere**: Acceso al repositorio, conexi├│n a internet (para links externos)
- **Dependencias**: Ninguna
- **Bloquea**: Ninguno
- **Agentes**: documentation-engineer

---

## Objetivo

Verificar que todos los enlaces en la documentaci├│n funcionan:
1. Enlaces internos (referencias a otros archivos .md)
2. Enlaces a c├│digo fuente
3. Enlaces externos (URLs)
4. Enlaces a im├ígenes y recursos
5. Anchors internos (#secci├│n)

---

## Tipos de Enlaces

| Tipo | Ejemplo | Validaci├│n |
|------|---------|------------|
| Interno relativo | `[link](./other.md)` | Archivo existe |
| Interno absoluto | `[link](/docs/file.md)` | Archivo existe |
| Anchor | `[link](#seccion)` | Header existe |
| Externo | `[link](https://...)` | URL responde 200 |
| Imagen | `![img](./img.png)` | Archivo existe |
| C├│digo | `[code](../src/file.cs)` | Archivo existe |

---

## Checklist Ejecutable

### 1. Identificar Archivos de Documentaci├│n

```bash
# Listar todos los archivos markdown
find . -name "*.md" -type f | grep -v node_modules | grep -v vendor | grep -v bin

# Contar archivos
find . -name "*.md" -type f | grep -v node_modules | wc -l
```

- [ ] Archivos .md identificados: ___
- [ ] Ubicaci├│n principal: docs/, README.md

### 2. Extraer Enlaces Internos

```bash
# Enlaces a otros archivos markdown
grep -ohE "\[.*\]\([^http][^)]*\.md[^)]*\)" docs/*.md README.md

# Enlaces a archivos de c├│digo
grep -ohE "\[.*\]\([^http][^)]*\.(cs|ts|js|py)[^)]*\)" docs/*.md

# Enlaces a im├ígenes
grep -ohE "!\[.*\]\([^)]+\)" docs/*.md README.md
```

- [ ] Enlaces internos extra├¡dos
- [ ] Enlaces a c├│digo extra├¡dos
- [ ] Im├ígenes extra├¡das

### 3. Validar Enlaces Internos

```bash
# Script para validar cada enlace interno
for file in $(find docs -name "*.md"); do
  # Extraer enlaces relativos
  links=$(grep -ohE "\]\([^http][^)]+\)" "$file" | sed 's/\](\|)//g')

  for link in $links; do
    # Resolver path relativo
    dir=$(dirname "$file")
    target="$dir/$link"

    # Limpiar anchor si existe
    target_file=$(echo "$target" | cut -d'#' -f1)

    if [ ! -f "$target_file" ]; then
      echo "ROTO: $file -> $link"
    fi
  done
done
```

- [ ] Todos los enlaces internos verificados
- [ ] Enlaces rotos identificados

### 4. Validar Anchors (#secciones)

```bash
# Extraer anchors usados
grep -ohE "\]\([^)]*#[^)]+\)" docs/*.md | sed 's/.*#\([^)]*\)).*/\1/'

# Para cada anchor, verificar que existe el header correspondiente
# Header "## Mi Secci├│n" genera anchor #mi-secci├│n
```

- [ ] Anchors verificados
- [ ] Anchors rotos identificados

### 5. Validar Enlaces Externos

```bash
# Extraer URLs externas
grep -ohE "https?://[^)\"' ]+" docs/*.md README.md | sort -u

# Verificar cada URL (con timeout)
for url in $(cat urls.txt); do
  status=$(curl -o /dev/null -s -w "%{http_code}" --max-time 10 "$url")
  if [ "$status" != "200" ]; then
    echo "ERROR $status: $url"
  fi
done
```

**C├│digos de respuesta:**

| C├│digo | Significado | Acci├│n |
|--------|-------------|--------|
| 200 | OK | V├ílido |
| 301/302 | Redirect | Actualizar URL |
| 403 | Forbidden | Verificar manualmente |
| 404 | Not Found | Enlace roto |
| 5xx | Server Error | Reintentar m├ís tarde |

- [ ] URLs externas verificadas
- [ ] Enlaces 404 identificados
- [ ] Redirects para actualizar

### 6. Validar Im├ígenes y Recursos

```bash
# Extraer rutas de im├ígenes
grep -ohE "!\[.*\]\([^)]+\)" docs/*.md | grep -oE "\([^)]+\)" | tr -d "()"

# Verificar que cada imagen existe
for img in $(cat images.txt); do
  if [[ "$img" != http* ]]; then
    if [ ! -f "docs/$img" ]; then
      echo "IMAGEN FALTA: $img"
    fi
  fi
done
```

- [ ] Im├ígenes verificadas
- [ ] Recursos faltantes identificados

### 7. Generar Reporte de Enlaces Rotos

```markdown
## Enlaces Rotos Encontrados

### Internos
| Archivo Origen | Enlace Roto | Sugerencia |
|----------------|-------------|------------|
| docs/api.md | ./old-file.md | Eliminar o crear archivo |

### Externos
| Archivo Origen | URL | C├│digo | Sugerencia |
|----------------|-----|--------|------------|
| README.md | https://old-site.com | 404 | Buscar nueva URL |

### Im├ígenes
| Archivo Origen | Imagen | Estado |
|----------------|--------|--------|
| docs/guide.md | ./img/old.png | No existe |
```

- [ ] Reporte generado
- [ ] Prioridades asignadas

---

## Herramientas Opcionales

```bash
# markdown-link-check (Node.js)
npm install -g markdown-link-check
markdown-link-check README.md
markdown-link-check docs/*.md

# Configuraci├│n personalizada
cat > .markdown-link-check.json << 'EOF'
{
  "ignorePatterns": [
    { "pattern": "^http://localhost" }
  ],
  "timeout": "10s",
  "retryOn429": true,
  "aliveStatusCodes": [200, 206]
}
EOF

# lychee (Rust, m├ís r├ípido)
lychee docs/**/*.md README.md

# linkinator (Google)
npx linkinator docs/ --recurse
```

---

## Output Esperado

```
====== PROC-08 COMPLETADO [TIMESTAMP] ======
Proyecto: [nombre]

ARCHIVOS ANALIZADOS: X

ENLACES TOTALES:
- Internos: X
- Externos: Y
- Im├ígenes: Z
- Anchors: W

RESULTADOS:
- Ô£à V├ílidos: X
- ÔØî Rotos: Y
- ÔÜá´©Å Redirects: Z
- ÔÅ│ Timeout: W

ENLACES ROTOS:
1. docs/api.md:25 -> ./missing.md (interno)
2. README.md:10 -> https://old.com (404)
3. docs/guide.md:50 -> #nonexistent (anchor)

REDIRECTS (actualizar):
1. https://old-url.com -> https://new-url.com

ACCIONES REQUERIDAS:
1. Corregir X enlaces rotos
2. Actualizar Y redirects
3. A├▒adir Z im├ígenes faltantes
```

---

## Criterios de ├ëxito

- [ ] 0 enlaces internos rotos
- [ ] 0 im├ígenes faltantes
- [ ] <5 enlaces externos rotos (pueden ser temporales)
- [ ] Redirects actualizados

---

## Alertas y Escalaci├│n

| Severidad | Condici├│n | Acci├│n |
|-----------|-----------|--------|
| WARNING | Enlaces internos rotos | Corregir antes de release |
| WARNING | Im├ígenes faltantes | A├▒adir o eliminar referencia |
| INFO | Enlaces externos 404 | Actualizar cuando sea posible |
| INFO | Todo v├ílido | Documentar buen estado |

---

## Automatizaci├│n

En ejecuci├│n no-interactiva:
1. Escanear todos los .md
2. Extraer y clasificar enlaces
3. Validar cada enlace
4. Generar reporte
5. Alertar si hay rotos cr├¡ticos

---

## Exclusiones Comunes

```json
{
  "ignorePatterns": [
    "localhost",
    "127.0.0.1",
    "example.com",
    "your-domain.com",
    "api.internal"
  ]
}
```

---


---

## 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-08 completada. [Descripcion breve de resultados]",
  "metrics": {
    "issues_found": 0,
    "issues_resolved": 0,
    "issues_found": 10, "issues_fixed": 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-08"]
    }
  ],
  "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:**
- links_checked, links_broken, links_fixed

**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 | Proyecto | Total Enlaces | Rotos | Redirects | Acciones |
|-------|----------|---------------|-------|-----------|----------|
| | | | | | |