Corrige y prueba un generador de envoltorios de bibliotecas nativas para muchos lenguajes

## Lee primero las guías de cada tarea y corrige las entradas, no los archivos generados ### Comienza con las instrucciones específicas de la tarea Antes de cambiar código o ejecutar comandos especializados, localiza las guías breves del repositorio para tareas concretas. Lee la guía que corresponda al trabajo en vez de reconstruir procedimientos a partir de una visión general. Las guías habituales cubren: - la ejecución de toda la batería, de una batería para un lenguaje de destino o de un único caso de prueba; - la depuración del compilador, la inspección de árboles sintácticos y el seguimiento de fallos de memoria; - la edición del manual de usuario y la validación de su estructura; - el formato del código fuente, los comentarios, las convenciones de contribución y los mensajes de commit; - la reproducción de fallos que solo aparecen en integración continua. Considera canónicas estas guías focalizadas cuando proporcionen comandos, opciones o convenciones exactas. Si alias de descubrimiento o enlaces simbólicos reflejan la misma guía en varias ubicaciones específicas de herramientas, mantén una sola fuente canónica y comprueba que los enlaces se materialicen correctamente en la plataforma de quien contribuye. ### Comprende el sistema antes de editarlo El repositorio implementa un generador de estilo compilador. Lee declaraciones nativas y descripciones de interfaces y luego genera envoltorios que exponen bibliotecas nativas a numerosos lenguajes de destino. Este modelo tiene tres consecuencias prácticas: - los archivos generados son productos, no el lugar principal para corregir el comportamiento; - las entradas de interfaz compartidas deben contener el comportamiento transversal a los lenguajes, mientras que las comprobaciones de ejecución específicas de un destino deben estar en el directorio de pruebas correspondiente; - un cambio en el análisis sintáctico, la resolución de tipos, la propiedad o la generación de envoltorios puede afectar a numerosos backends, aunque el síntoma comunicado aparezca en uno solo. Usa como pruebas las propias guías, los archivos de compilación y las pruebas del repositorio. No deduzcas un flujo únicamente de nombres de directorio que resulten familiares o de convenciones utilizadas por otro proyecto. ## Compila con el sistema de build de CI y elige la prueba útil más pequeña ### Compila desde la forma de código fuente correcta Usa el sistema de compilación principal empleado por la integración continua. Una copia de trabajo extraída del control de versiones puede requerir un paso de arranque para generar archivos de configuración, mientras que un archivo de distribución puede incluirlos ya. La secuencia normal es ejecutar el arranque cuando sea necesario, configurar y después compilar. Conserva las opciones de configuración admitidas, como el prefijo de instalación y los controles de dependencias opcionales. Puede existir un sistema de compilación secundario, pero no lo sustituyas silenciosamente al diagnosticar un fallo de la canalización principal. Las pruebas y los ejemplos pueden invocar un lanzador para el árbol sin instalar que dirija el entorno de ejecución al directorio de la biblioteca recién compilada; utiliza ese lanzador para que las pruebas examinen la copia actual y no una versión instalada. Si un componente auxiliar de caché del compilador forma parte del grafo predeterminado de compilación y pruebas, inclúyelo salvo que la guía canónica limite expresamente la ejecución. ### Elige la prueba significativa más pequeña Ajusta el comando al alcance del cambio: - ejecuta una prueba de envoltorio generado mientras iteras sobre un comportamiento localizado; - ejecuta toda la batería del lenguaje de destino afectado cuando cambie el comportamiento del backend; - ejecuta las baterías compartidas cuando cambien el analizador, el sistema de tipos, la propiedad o la lógica común de generación; - usa ejecución paralela solo cuando el repositorio la admita; - usa un modo que continúe ante errores en ejecuciones amplias cuando sea más útil recopilar todos los fallos que detenerse en el primero. Los destinos de prueba suelen codificar la forma del código fuente, como el modo de lenguaje nativo, el modo orientado a objetos o el modo de varios módulos. Usa el sufijo que corresponda al caso y ejecuta el destino de limpieza asociado antes de suponer que un producto generado obsoleto es un fallo nuevo. ### Verifica la misma ruta que utiliza la automatización Cuando un fallo ocurra solo en integración continua, reproduce el entorno del ejecutor con la imagen de contenedor mantenida por el repositorio y los scripts reales de instalación. Prefiere el auxiliar que replica el ejecutor alojado a un entorno improvisado. Confirma que coincidan las versiones de dependencias, las variables de entorno, el modo de compilación y el destino de prueba antes de atribuir la diferencia al código fuente. Una corrección o funcionalidad normalmente debe incluir una prueba de regresión. No afirmes que un cambio está verificado solo porque el compilador se haya construido correctamente; la generación del envoltorio, la compilación del código generado y el comportamiento de ejecución en el lenguaje de destino son puntos de control independientes. ## Encuentra la etapa del proceso donde empieza el fallo y no reentres en el analizador ### Sigue las etapas de procesamiento Sigue el comportamiento por la canalización en este orden: 1. El preprocesador expande las entradas de interfaz y las directivas condicionales. 2. El escáner convierte el texto de entrada en tokens. 3. El analizador aplica la gramática y crea un árbol de nodos con atributos. 4. El sistema de tipos resuelve nombres, equivalencias, plantillas y conversiones. 5. Las pasadas sobre el árbol añaden o normalizan la información que necesitan las etapas posteriores. 6. Un backend del lenguaje de destino recorre el árbol y genera el código del envoltorio. Localiza la primera etapa en la que el estado real se desvíe del esperado. Un envoltorio mal formado no demuestra que el backend sea responsable; este puede estar generando fielmente un nodo sintáctico, tipo, indicador de propiedad o regla de conversión incorrectos creados en una etapa anterior. ### Usa las abstracciones centrales del modelo Los nodos sintácticos se comportan como objetos de clave y valor y son recorridos por pasadas compartidas y backends de lenguaje. Inspecciona los atributos cuando se crean y de nuevo cuando se consumen. Los mapas de conversión de tipos controlan cómo atraviesan la frontera los valores nativos para convertirse en valores del lenguaje de destino; cuando la conversión sea incorrecta, comprueba la prioridad de selección y la equivalencia de tipos antes de modificar el texto generado. La instanciación de plantillas depende del mismo mecanismo de equivalencia de tipos, por lo que debes separar la coincidencia de especializaciones del formato del envoltorio. Examina el análisis compartido de propiedad y asignación antes de añadir soluciones locales de ciclo de vida en un backend. ### Respeta los límites de un analizador no reentrante Supón que el analizador no es reentrante, salvo que la implementación demuestre lo contrario. Los puntos de entrada que lo envuelven pueden sobrescribir el estado global del analizador, incluida la posición actual de entrada, los valores semánticos y la anticipación. Nunca llames recursivamente a esos puntos de entrada desde una acción gramatical. Cuando una regla gramatical necesite construir una nueva lista de parámetros o una subsintaxis relacionada, reutiliza las producciones existentes de la gramática dentro del análisis activo, en vez de iniciar un análisis anidado. Valida el cambio con un caso de regresión para el estándar de lenguaje más antiguo que introdujo la característica gramatical. ### Usa los mecanismos de depuración admitidos Usa las opciones de depuración documentadas en el repositorio, los volcados textuales o estructurados del árbol, los auxiliares del depurador, los envoltorios de ejecución, las variables de selección de características y los diagnósticos del pool de memoria. Ante un fallo exclusivo de la automatización, reproduce su entorno antes de ampliar la instrumentación. Mantén temporales los cambios de diagnóstico y no conviertas una solución local en comportamiento de producción sin una prueba fallida que demuestre la necesidad. ## Coloca cada prueba de regresión en la entrada compartida o en el script del lenguaje ### Coloca el comportamiento en la capa adecuada Una prueba suele incluir una entrada de interfaz compartida que impulsa la generación y un script opcional de ejecución en el lenguaje de destino que ejercita el envoltorio generado. Coloca en la entrada compartida los requisitos de gramática y envoltorio independientes del lenguaje. Coloca en el script correspondiente la sintaxis del lenguaje de destino, las aserciones en ejecución y los casos límite específicos del lenguaje. Registra los casos nuevos en el grupo de la batería que corresponda a su alcance real. Un prefijo de nombre de prueba ligado a un estándar de lenguaje debe representar el estándar más antiguo que introdujo la característica gramatical, no uno más reciente utilizado por un ejemplo conveniente. Determina la característica de forma aislada y coloca después la prueba en el grupo del estándar correspondiente. ### Haz observables los fallos Usa auxiliares de aserción que permanezcan activos en modos de ejecución optimizados. Si un lenguaje de destino puede eliminar su sentencia de aserción integrada durante la optimización, nunca dependas de ella para la cobertura de regresión. Usa auxiliares explícitos de igualdad, condición y excepción esperada que informen valores útiles al fallar. Mantén breves los comentarios de las pruebas y limita su contenido a lo que no resulte evidente. Explica una solución provisional del compilador o una trampa semántica en una línea concisa; no narres lo que el código ya expresa. Una prueba de regresión debe fallar antes de la corrección, pasar después y ejercitar el comportamiento público en vez de un auxiliar interno accidental. ### Valida el impacto compartido Para cambios del analizador o del sistema de tipos común, prueba más backends que el que falló originalmente cuando la ruta afectada sea compartida. Para un comportamiento exclusivo del backend, evita ampliar la ejecución sin pruebas que lo justifiquen. Limpia los archivos generados entre configuraciones de prueba sustancialmente diferentes y distingue en el informe los fallos de generación, compilación nativa y ejecución. ## No mezcles cambios ajenos en los commits y anota cada cambio visible en el registro de cambios ### Sigue las convenciones del código fuente y los comentarios Usa las comprobaciones de formato y el formateador del repositorio, en lugar de normalizar manualmente código no relacionado. Respeta el estilo establecido de comentarios del lenguaje nativo, las comillas para tokens, el ancho de línea y las convenciones de cabecera de funciones. Los archivos de gramática pueden imponer reglas más estrictas al código nuevo; síguelas y evita refactorizaciones no relacionadas mientras cambias un analizador de producción. Antes de confirmar cambios, revisa el diff en busca de archivos generados, sustituciones amplias accidentales y cambios fuera del subsistema previsto. El texto del commit debe ser claro, conciso y exacto. No atribuyas una herramienta automatizada como coautora. Si el proyecto exige revelar una asistencia automatizada significativa, usa su pie de asistencia aprobado sin una identidad de correo electrónico. ### Registra los cambios visibles para los usuarios Cada corrección de defecto, funcionalidad, cambio de comportamiento, cambio de advertencia o desuso visible para los usuarios debe incluir una entrada en el registro de cambios actual. Describe lo que observa el usuario, no nombres de auxiliares internos ni detalles de refactorización. Sigue el formato establecido de fecha e issue, coloca las entradas nuevas en el orden esperado y marca explícitamente los riesgos de compatibilidad. Los cambios puramente internos sin efecto observable no necesitan una entrada para usuarios. ### Mantén la documentación para desarrolladores y usuarios Al editar el manual, conserva anclas de encabezado estables y descriptivas, en lugar de anclas numéricas generadas. Usa las clases de contenido documentadas para código, ejemplos del lenguaje de destino, sesiones de shell y diagramas. Mantén los enlaces entre documentos anclados a destinos estables y ejecuta después el generador de la tabla de contenido y las comprobaciones de documentación. La documentación para desarrolladores debe explicar el modelo interno de objetos, los atributos del árbol, el sistema de tipos y la ruta de extensión. La documentación para usuarios debe centrarse en la sintaxis admitida y el comportamiento observable. Verifica tanto la estructura renderizada como los destinos de los enlaces; editar correctamente el código fuente no demuestra por sí solo que el manual siga siendo navegable.