Crear reglas de un verificador de accesibilidad que devuelvan aprobado, fallo o incompleto

## Trata el lint y las pruebas como parte del cambio, no como limpieza Trata el formato, el lint, las pruebas, la documentación y las convenciones de commit como parte del cambio, no como tareas de limpieza posteriores a la implementación. ### Comprobaciones obligatorias - Ejecuta el formateador y el linter del repositorio antes de realizar el commit. - Ejecuta el conjunto completo de pruebas antes de terminar, con cobertura unitaria y de integración para los cambios de comportamiento. - Sigue las excepciones documentadas únicamente para cambios que no puedan afectar al comportamiento en tiempo de ejecución. - Mantén el trabajo sin resolver en el gestor de incidencias del proyecto, en lugar de ocultarlo en cambios no relacionados. - No incluyas en el commit registros temporales ni ajustes locales de depuración. ### Convenciones de código - Gestiona pronto los errores y los casos límite para que la ruta correcta siga siendo fácil de seguir. - Respeta la ubicación establecida para los export, las reglas de nomenclatura y el estilo de los import. - Asigna nombres coherentes a los archivos y los identificadores de reglas; distingue funciones, booleanos y constantes según las convenciones del proyecto. - Declara las variables cerca de su primer uso. - Documenta las API exportadas, los parámetros, los valores devueltos y la lógica compleja. - Mantén la refactorización separada de una función o corrección con un alcance definido. ## Elige entre nodos virtuales y DOM real, y mantén las dependencias en un solo sentido Elige deliberadamente entre una abstracción de árbol virtual y nodos DOM reales. La abstracción es eficiente para atributos y propiedades almacenados en caché, mientras que el DOM real es necesario para las API del navegador y el comportamiento del diseño. ### Selección de nodos - Prefiere los nodos virtuales para acceder a atributos, usar propiedades almacenadas en caché, recorrer árboles y trabajar con selectores. - Utiliza nodos DOM reales para el diseño, la geometría, la búsqueda de la raíz, el comportamiento calculado por el navegador y otras API nativas. - Resuelve las entradas ambiguas mediante un único límite de conversión documentado. - Mantén las utilidades generales basadas en entradas y salidas de DOM real, salvo que una dependencia de nodos virtuales aporte una ventaja clara de API o rendimiento. - No disperses la lógica de conversión entre reglas individuales. ### Dirección de las dependencias - Mantén las definiciones de estándares como datos puros, sin import en tiempo de ejecución. - Permite que las utilidades de bajo nivel dependan únicamente de código base de nivel inferior y de datos de estándares mediante rutas explícitas. - Centraliza los import de módulos de terceros en una capa adaptadora designada. - Permite que los auxiliares compartidos del dominio utilicen las utilidades de bajo nivel, pero nunca inviertas esa dependencia. - Permite que las comprobaciones y reglas de alto nivel compongan las capas inferiores sin crear ciclos. - Aplica estos límites de forma mecánica mediante reglas de lint o de compilación. ## Devuelve aprobado, fallo o incompleto y guarda los mensajes en metadatos Explicita el contrato de resultados para que quienes lo consumen puedan distinguir cumplimiento, fallo y evidencia insuficiente. ### Resultados de las comprobaciones - Devuelve `pass` cuando se cumpla la condición comprobada. - Devuelve `fail` cuando se incumpla la condición comprobada. - Devuelve `incomplete` cuando el motor no pueda determinar el resultado de forma fiable. - Adjunta datos estructurados para las plantillas de mensajes y para explicar los resultados `incomplete`. - No fuerces la incertidumbre a convertirse en `pass` o `fail` solo para producir una respuesta binaria. ### Definiciones de reglas - Combina las comprobaciones con grupos explícitos `all`, `any` y `none`. - Delimita los elementos candidatos mediante un selector y un comparador adicional opcional. - Restringe el impacto a los valores de gravedad declarados por el proyecto. - Lee las definiciones de HTML y ARIA desde datos de estándares centralizados, en lugar de codificar listas directamente en las comprobaciones. ### Mensajes para las personas usuarias - Mantén los mensajes en los metadatos de la regla o la comprobación, no en el código de implementación. - Utiliza marcadores de posición de datos con nombre cuyos valores procedan del resultado de la comprobación. - Proporciona variantes en singular y plural cuando lo exija la gramática. - Actualiza la plantilla de localización siempre que cambie un mensaje de origen. ## Revisa con especial cuidado el contraste de color y la validación de roles Algunos resultados de accesibilidad dependen de información incompleta del navegador o de estándares que evolucionan rápidamente. Estas áreas requieren resultados prudentes y una revisión específica. ### Color y visibilidad - Ten en cuenta los formatos de color compatibles, la opacidad, la mezcla, los contextos de apilamiento y los efectos de texto. - Devuelve `incomplete` cuando no se pueda determinar el fondo efectivo o el contraste. - Evalúa semánticamente la visibilidad para lectores de pantalla, en lugar de depender únicamente de la visibilidad de CSS. - Incluye los atributos de estado oculto, los árboles compuestos y los límites de Shadow DOM. ### Estándares semánticos - Mantén la validación de `role` y atributos sincronizada con la especificación de accesibilidad vigente. - Resuelve por separado los `role` implícitos y explícitos. - Consulta las definiciones centralizadas de `role` y atributos para que todas las reglas utilicen la misma fuente de verdad. - Añade casos de regresión para las actualizaciones de la especificación y el marcado que se haya clasificado incorrectamente con anterioridad. - Exige una revisión específica cuando un cambio pueda alterar los resultados de muchas reglas. ## Prueba cada regla en páginas realistas, incluido Shadow DOM Refleja la estructura del código fuente en el árbol de pruebas unitarias para que la propiedad de la implementación y de las pruebas siga siendo evidente. ### Pruebas unitarias y de comprobaciones - Utiliza el contexto de comprobación estándar o el harness que proporcione el proyecto. - Restablece únicamente el estado que pertenezca a la prueba cuando el harness ya haya limpiado los fixture compartidos y los árboles virtuales. - Prueba los resultados `pass`, `fail` e `incomplete`, incluidos los datos de mensaje adjuntos. - Añade casos específicos para condiciones límite antes de ampliar la cobertura de integración. ### Pruebas de integración - Asocia cada fixture de regla con resultados esperados estructurados. - Utiliza la representación canónica de selectores del motor, incluidos los selectores anidados para frame. - Utiliza una página HTML completa cuando el comportamiento a nivel de documento no pueda representarse mediante un fragmento. - Añade un caso de open Shadow DOM para cada regla o comprobación pertinente. - Actualiza la cobertura de reglas virtuales cuando un cambio afecte a la evaluación del árbol virtual. - Ejecuta pruebas específicas durante la iteración y el conjunto completo y definitivo antes de la entrega. ## Regenera las plantillas de traducción en el mismo commit que los mensajes Distingue los paquetes de publicación generados de los artefactos de código fuente generados que el repositorio rastrea de forma intencionada. ### Política de artefactos - No edites directamente la salida de publicación empaquetada o minificada. - Vuelve a generar las plantillas o los artefactos de código fuente rastreados mediante el proceso de compilación aprobado. - Incluye una plantilla de localización generada en el mismo cambio que el mensaje de origen que la produjo. - No dividas las actualizaciones sincronizadas del código fuente y de los elementos generados en commits distintos. - Mantén los paquetes de publicación ignorados fuera de los commits ordinarios de funciones. ### Verificación - Inspecciona el diff generado para detectar cambios inesperados de mensajes, configuraciones regionales o reglas. - Confirma que cada nuevo marcador de posición exista en los datos de la comprobación que lo produce. - Ejecuta la validación de localización y compilación después de cambiar mensajes. - Documenta qué artefactos se generan, cuáles se rastrean y cuáles se usan solo para publicaciones. ## Actualiza el changelog y la documentación de la API, y evita cambios incompatibles Mantén cada cambio centrado y haz visibles sus consecuencias públicas para quienes revisan y utilizan el proyecto. ### Documentación de cambios - Actualiza el registro de cambios cuando añadas o modifiques de manera sustancial una regla. - Actualiza conjuntamente la documentación de la API y las definiciones de tipos cuando cambie una interfaz pública. - Utiliza el formato de conventional commit exigido por el repositorio, con un asunto conciso y la motivación en el cuerpo. - Vincula la incidencia resuelta mediante el footer admitido o los metadatos de la solicitud de incorporación de cambios. - Completa la lista de revisión del proyecto antes de la entrega. ### Compatibilidad - Evita cambios incompatibles cuando los formatos antiguos y nuevos puedan admitirse simultáneamente. - Marca claramente las API obsoletas y proporciona una ruta de migración. - Cuando una incompatibilidad sea inevitable, identifícala de forma explícita en los metadatos de publicación y en el registro de cambios. - Incluye instrucciones de migración, pruebas actualizadas, archivos generados sincronizados y pruebas visibles para quienes revisan. - No declares que el cambio está listo hasta que el formato, el lint, las pruebas específicas, las pruebas de integración, el conjunto completo y las comprobaciones de documentación tengan resultados reales.