Project Audit

Project Audit — Auditoría de Coherencia de Proyectos

Resumen

Patrones para auditar la consistencia de proyectos: verificar que documentación, código, especificaciones, ejemplos y validadores dicen lo mismo. Detectar desviaciones estructurales antes de que se propaguen.

Patrón 1: Auditoría de Coherencia Cruzada

Cuando un proyecto tiene múltiples artefactos interconectados (DECISIONES.md, README, spec, código generador, ejemplos XML/JSON, validador, tests), ejecutar una auditoría automática antes de dar por terminado un cambio.

Pasos

1. Identificar artefactos clave:

   • Documento de decisiones (DECISIONES.md, DESIGN.md, etc.)
   • README principal
   • Especificación técnica (spec/, docs/)
   • Código generador/conversor
   • Ejemplos en formato objetivo
   • Validador / tests
   • Interfaz de usuario (HTML, app, etc.)

2. Extraer texto de cada artefacto:

   def read_file(path):
       with open(path) as f:
           return f.read()
   

3. Definir dimensiones de coherencia (una por cada decisión estructural clave):

   • Ejemplo NeTEx: dataObjects eliminado, ParticipantRef mayúscula, 6 frames tipados, ScheduledStopPoint en vez de PassengerStoppingArea, Tariff en vez de FareStructure, FrameDefaults eliminado
   • Cada dimensión se verifica como booleana (presente/ausente) en cada artefacto

4. Verificar cada dimensión en cada artefacto:

   for name, text in [("DECISIONES", dec), ("README", readme), ("spec", spec), ...]:
       has_x = keyword in text
       has_wrong_y = "wrong_term" in text  # término obsoleto
       status = "✅" if has_x and not has_wrong_y else "❌"
   

5. Reportar resultados: mostrar una tabla de estado por dimensión × artefacto

Reglas del patrón

• Solo auditar decisiones estructurales, no detalles menores
• Los términos obsoletos deben marcarse con ~~ en documentación para que no se detecten como "presentes" en auditorías automatizadas simples
• Si una dimensión falla en 2+ artefactos → es un problema real, no ruido

Patrón 2: Detección de Desviaciones Estructurales

Cuando se pide modificar un formato o esquema, verificar que la modificación propuesta es compatible con las restricciones del estándar base antes de aplicar cambios masivos.

Secuencia

1. Identificar el estándar base (XSD oficial, protocolo, formato)
2. Descargar la definición oficial (repositorio del estándar, documentación)
3. Verificar la compatibilidad de la propuesta con el estándar antes de modificar código
4. Si es incompatible, documentar por qué y proponer alternativas:
   • Adaptar a estándar (coste de mantenimiento alto pero compatibilidad total)
   • Perfil propio (coste de compatibilidad pero estructura propia)
   • Híbrido (validación XSD + validador propio encima)

Pitfall crítico

NUNCA eliminar elementos del XML sin verificar si el XSD/estándar base lo exige.

Ejemplo: NeTEx-CEN 1.14 requiere <dataObjects><CompositeFrame>...</CompositeFrame></dataObjects> en PublicationDelivery. Eliminar dataObjects rompe XSD validation. Si se quiere estructura propia, hay que adoptar explícitamente el modelo de "perfil propio" y documentarlo.

Patrón 3: Validación Post-Refactor

Después de un rewrite de estructura:

1. Ejecutar todos los tests existentes
2. Regenerar el ejemplo con el código nuevo
3. Verificar la estructura generada contra la especificación
4. Actualizar el ejemplo en spec/examples/ para que coincida con la generación real
5. Re-auditar coherencia cruzada

Registros

Ver references/netex-audit-2025-07-07.md para el caso de estudio NeTEx-ES.