audit-html-project

# Audit HTML Project — Auditoría Sistemática de Proyectos HTML Procedimiento para auditar proyectos HTML grandes (10+ archivos) de forma sistemática y eficiente. ## Cuándo usar - Proyecto HTML con 10+ archivos y el usuario reporta errores - Antes de hacer commit/push a un repositorio de contenido educativo - Cuando se genera contenido HTML masivamente y se necesita QA - Cuando un sitio estático muestra errores de navegación - **SPA con backend (Express + Chart.js + Three.js)** — auditoría de endpoints, sync de datos, responsive de componentes JS, estado de DB ## Pasos ### 1. Inventario del proyecto ```python import os base = "/path/to/project" html_files = [f for f in os.listdir(base) if f.endswith('.html')] # Clasificar por tipo: páginas de contenido, páginas índice, archivos de navegación ``` ### 2. Detección de errores sistemáticos Escanear cada archivo por estos problemas: **Críticos (❌):** - Sin atribución correcta (`David Antizar` + `❤️`) - Navegación rota: `href="#">` con texto "Anterior" o "Siguiente" - Enlaces rotos internos: referencias a archivos que no existen **Advertencias (⚠️):** - Sin ejercicios interactivos (en contenido educativo) - Sin resumen final - Sin sección de teoría - Sin ejemplos - Sin caja de error frecuente o idea clave - Sin barra de progreso - Contenido inexistente (páginas de volumen vacías) ### 3. Clasificar por severidad 1. **Bloqueantes** — navegación rota, enlaces rotos, contenido inexistente 2. **Importantes** — atribuciones incorrectas, sin resumen 3. **Mejora** — sin ejercicios, sin ejemplos ### 4. Estrategia de escaneo para proyectos grandes (30+ archivos) Para proyectos con 30+ archivos HTML, **NO usar `read_file` por cada archivo** — es lento y consume el límite de tool calls. Usar `grep` vía terminal para el escaneo inicial: ```bash # Escaneo masivo de atribución grep -c 'David Antizar' *.html | grep ':0$' # Escaneo de KaTeX grep -c 'katex' *.html | grep ':0$' # Enlaces a archivos que no existen for f in *.html; do grep -oP 'href="[^"]*\.html"' "$f" | while read -r href; do target=$(echo "$href" | sed 's/href="//;s/"//') [ ! -f "$target" ] && echo "ROTO: $f → $target" done done ``` Luego, para las fases de corrección y verificación profunda, usar `execute_code` con Python y un solo script que procese todos los archivos. ### 5. Corrección en lotes Usar `execute_code` con Python para batch-fix: ```python from hermes_tools import read_file, write_file, patch import os base = "/path/to/project" html_files = sorted([f for f in os.listdir(base) if f.endswith('.html')]) all_set = set(html_files) # Ejemplo: corregir todas las atribuciones files = ['s09-3-bachiller.html', 's10-1-carrera.html', ...] for f in files: content = read_file(path=os.path.join(base, f)).get('content', '') content = content.replace("corazón", "❤️") write_file(path=os.path.join(base, f), content=content) ``` #### 5.1 Añadir CDN faltante (KaTeX, Plotly.js, etc.) Para proyectos educativos con contenido matemático, verificar si KaTeX está presente y añadirlo si falta: ```python katex_cdn = '''<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.css"> <script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.js"></script> <script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/contrib/auto-render.min.js" onload="renderMathInElement(document.body,{delimiters:[{left:'\\\\[',right:'\\\\]',display:true},{left:'\\\\\\(',right:'\\\\)',display:false}]})"></script>''' for fname in archivos_sin_katex: content = read_file(path=join(base, fname)).get('content', '') new_content = content.replace('</title>', f'</title>\n{katex_cdn}', 1) write_file(path=join(base, fname), content=new_content) ``` **Regla:** KaTeX SOLO para niveles donde haya fórmulas (ESO, Bachiller, Universidad). Primaria usa emojis y texto plano — no necesita KaTeX. #### 5.2 Crear índices de nivel faltantes Cuando un nivel (ej: 1º Primaria) carece de índice, y otros niveles (4º+) sí tienen, crear el índice replicando el diseño visual y estructural de los existentes: ```python # 1. Identificar un índice de referencia (ej: s04-4primaria.html) # 2. Extraer su estructura: header, grid de tarjetas, colores, footer # 3. Mapear las sesiones reales del nivel # 4. Generar el nuevo índice con ese mismo diseño ``` El nuevo índice debe incluir: - Header con título y descripción del nivel - Grid de tarjetas, UNA por sesión, con: título, descripción corta, tag/tema - Cada tarjeta enlaza a su sesión correspondiente - Footer con atribución y enlace "Volver al índice general" - Misma paleta de colores y glassmorphism que los índices existentes **Regla:** NO reutilizar nombres de archivo existentes. Si `s01-1primaria.html` ya existe y es una sesión, crear `s01-1primaria-index.html` como índice. ### 6. Verificación post-corrección Re-ejecutar el escáner para confirmar que todos los errores se resolvieron. Usar un script de verificación único que cubra **8 checks**: ```python print('1. ENLACES ROTOS:') # 0 = perfecto print('2. ATRIBUCION:') # 0 = perfecto print('3. KATEX:') # 0 en niveles que lo necesitan print('4. NUEVOS INDICES:') # existen los que creamos print('5. INDEX.HTML ENLACES:') # apuntan a los nuevos índices print('6. ENLACES CORREGIDOS:') # los targets rotos ya no aparecen print('7. CONEXION CADENAS:') # cadenas paralelas conectadas print('8. INDEX.HTML ATRIBUCION:') # tiene footer ``` ## Formato de salida (preferido por el usuario) El usuario pide auditorías "estrictas y críticas" que "expliquen todo bien". Usar este formato: ```markdown # 🔍 AUDITORÍA COMPLETA — [Nombre del Proyecto] **Proyecto:** [Descripción] **Archivos HTML:** [N] --- ## 📊 RESUMEN EJECUTIVO | Severidad | Encontrados | Estado | |-----------|------------|--------| | ❌ **Críticos** | N | [resumen] | | ⚠️ **Importantes** | N | [resumen] | | 💡 **Mejoras** | N | [resumen] | --- ## ❌ ERRORES CRÍTICOS ### 1. [Descripción del error] [Tabla con archivos afectados y detalle del error] **Impacto:** [Qué le pasa al usuario/alumno] --- ## ⚠️ PROBLEMAS IMPORTANTES [Similar formato] --- ## 💡 MEJORAS SUGERIDAS [Similar formato] --- ## ✅ LO QUE FUNCIONA BIEN [Bullet points positivos] --- ## 📋 PLAN DE CORRECCIÓN Si quieres que arregle todo, el orden sería: 1. **Fase 1 (Crítico):** [Acción] 2. **Fase 2 (Crítico):** [Acción] ... ``` **Regla:** SIEMPRE terminar con "¿Quieres que empiece a corregir?" — el usuario quiere acción, no solo diagnóstico. ## Reglas - **NUNCA modificar la estructura de navegación** de sesiones individuales (eso es responsabilidad del generador) - **Las páginas de volumen** (nivel educativo completo) deben ser índices funcionales con: título, descripción, lista de sesiones con enlaces, objetivos de aprendizaje y resumen - **El INDEX.html** debe reflejar correctamente el contenido real (niveles, etiquetas, descripciones) - **Siempre verificar** que los archivos referenciados existen antes de corregir enlaces - **Commit y push** tras las correcciones - **RITMO: no parar entre pasos** — El usuario frustración = "¿por qué has parado?". Flujo: terminar un fix → siguiente inmediatamente. Mostrar progreso en vivo, no esperar a tener todo perfecto para comunicar. Si hay 3+ fixes, hacerlos secuencialmente sin preguntar entre cada uno. ## Flujo post-auditoría: fix → generate → deploy Cuando el usuario pide "arreglar y completar" tras una auditoría, el flujo natural es: 1. **Fix crítico** → corregir enlaces rotos, atribuciones, navegación (usar `execute_code` + `patch` para fixes simples, `write_file` para HTML completo) 2. **Fix importante** → actualizar trackers (progress.json, README, etc.) — **⚠️ NO usar `read_file` para JSON** (prependea números de línea), usar `terminal("cat ...")` + `json.loads()` 3. **Generar contenido faltante** → cargar skill del dominio, generar HTML con template, verificar calidad (>12KB, SVG, ejercicios) 4. **Actualizar índice** → INDEX.html con todos los temas 5. **Deploy** → git push (Pages se activa automático si repo es público) ### Cada fase → commit separado - `🔧 Fix: <descripción>` para correcciones - `📝 <bloque>: <temas generados>` para contenido nuevo - `INDEX: actualizado con N temas` para actualización del índice ## Pitfalls - **🔴 CSS CON DOBLES LLAVES `{{}}` DE TEMPLATE ENGINE** — Algunos archivos HTML generados por scripts Python/Jinja pueden contener `{{` y `}}` en lugar de `{` y `}` en bloques `<style>`. Esto rompe TODOS los estilos CSS del archivo. **Detección:** `grep -n '{{' *.html` dentro de bloques `<style>`. **Corrección:** reemplazar `{{` → `{` y `}}` → `}` SOLO dentro de `<style>` tags (nunca en HTML content). **Prioridad:** ❌ Crítico — el archivo se ve sin estilos. Ver `references/css-double-braces-fix.md` para patrón de corrección batch. - **🔴 PREFIJOS DE LÍNEA `N|` EN HTML** — Archivos HTML contienen prefijos tipo `1|`, ` 2|` al inicio de cada línea. Causa CSS destruido + texto basura visible. Origen: output de tools de visualización de código guardado como archivo real. **Detección:** `grep -rlP '^\s*\d+\|' *.html`. **Corrección:** `re.sub(r'^\s*\d+\|', '', content, flags=re.MULTILINE)`. **Trampa:** `read_file` de Hermes SIEMPRE prependea `N|` — no confundir con corrupción real. Usar `terminal("head -5 file")` para verificar contenido real. Ver `references/line-number-prefix-corruption.md`. - **🔴 NÚMEROS DE LÍNEA INCORPORADOS EN HTML (`N|` PREFIX)** — Archivos HTML pueden contener prefijos tipo `52|` o ` 3|` al inicio de cada línea. Causa: una herramienta escribe el output de `read_file()` (que prependea números de línea) de vuelta al archivo. **Síntomas:** números como texto visible en la página, CSS roto (números dentro de `<style>`), contenido renderizado con basura. **Detección:** `grep -cP '^\s*\d+\|' *.html | grep -:0$` — si algún archivo tiene matches, está corrompido. **Corrección:** `re.sub(r'^\s*\d+\|', '', content, flags=re.MULTILINE)` para eliminar todos los prefijos. **Prioridad:** ❌ Crítico — el archivo se ve completamente roto. Ver `references/line-number-corruption-fix.md` para patrón de detección y corrección. - **🔴 `write_file` DOBLE-ESCAPA BACKSLASHES EN REGEX** — Cuando `write_file` escribe código que contiene patrones regex como `new RegExp('[\\s\\S]*?')` o `/\\d+/g`, el tool puede duplicar los backslashes (escritura: `[\\s\\S]` → archivo: `[\\\\s\\\\S]`). El regex queda roto silenciosamente — el código pasa `node --check` pero no funciona en runtime. **Detección:** `grep -n '\\\\\\\\' file.js` — si hay resultados sospechosos, hay doble-escape. **Prevención:** Usar `indexOf`/`substring` en vez de regex para patrones simples (limpiar tags, extraer JSON). Si se necesita regex, verificar el contenido real con `cat -n file | grep 'pattern'` tras escribir. **Trampa:** `read_file` de Hermes también puede mostrar doble-escape — usar `terminal("cat -n file")` para verificar el contenido real del archivo. Ver `pdf-to-landing/references/server-2-endpoint-pattern.md` para ejemplo completo. - **🔴 `write_file` CORROMPE CONTENIDO COMPLEJO (NO solo prefijos de línea)** — Cuando se usa `read_file` dentro de `execute_code` para leer HTML/JS y luego `write_file` para escribir de vuelta (incluso después de procesar), el contenido puede corromperse: strings truncados, secuencias de escape rotas, caracteres UTF-8 mangled. Esto ES DIFERENTE al pitfall de prefijos `N|` — aquí el problema es que `write_file` dentro de `execute_code` puede truncar o corromper datos dentro de strings JavaScript complejos (arrays de objetos, datos con caracteres especiales). **Síntomas:** `SyntaxError: Invalid or unexpected token` en Node.js, navegador no ejecuta inline scripts, datos de referencia (como `_contractTypes`) truncados. **Detección:** `node --check` falla. **Corrección:** Restaurar desde el último commit funcional (`git show COMMIT:index.html`). **Prevención:** NUNCA usar `write_file` para reescribir archivos completos con contenido JS/CSS complejo extraído de `read_file` dentro de `execute_code`. Usar `patch` con `old_string`/`new_string` para ediciones específicas. Ver `references/write-file-corruption-pattern.md` para el caso completo. - **🔴 BATCH FIX SOBRESCRIBE CORRECCIONES ANTERIORES** — Si haces múltiples fases de corrección (ej: Fase 2 añade transiciones, Fase 5 reconstruye navegación), la Fase 5 puede sobrescribir lo que hiciste en Fase 2. **SOLUCIÓN:** Al hacer batch-fix de navegación, PRESERVAR los enlaces de transición entre niveles que ya existían. Marcarlos antes del batch y re-insertarlos después. Verificar con test específico post-fix. - **🔴 FÓRMULAS KATEX COMO TEXTO PLANO** — Las fórmulas pueden estar escritas como texto (`R²`, `{(1,0), (0,1)}`) en lugar de KaTeX (`$R^2$`, `$\\{(1,0), (0,1)\\}$`). El CDN de KaTeX puede estar cargado pero las fórmulas no se renderizan porque no tienen delimitadores `$`. **SIEMPRE** verificar: (1) KaTeX CDN presente, (2) script auto-render con delimiters, (3) fórmulas envueltas en `$...$` o `$$...$$`. Detectar con: `re.findall(r'(?<!\\$)R[²³](?!\\$)', content)`.