Añadir extensiones de archivo o lenguajes nuevos a un repositorio de detección de lenguajes

## Identificar qué archivos y herramientas gestionan cada parte de la detección Antes de editar, identifica qué archivos y herramientas controlan cada parte de la detección de lenguajes: - el registro de lenguajes para nombres, extensiones, nombres de archivo y propiedades del lenguaje; - las reglas heurísticas y su implementación para archivos ambiguos; - el clasificador estadístico y su corpus de muestras reales; - el registro de gramáticas utilizado para el resaltado de sintaxis; - las fuentes de gramáticas incorporadas y los datos de licencias almacenados en caché; - los scripts de mantenimiento, las pruebas y los puntos de entrada de la integración continua. Trata estos elementos como contratos coordinados. Un cambio de metadatos puede requerir muestras, heurísticas, identificadores generados, datos de gramática, pruebas y evidencias, en lugar de una única edición aislada. ## Preparar el proyecto en el contenedor de desarrollo y usar sus scripts Cuando esté disponible, prefiere el contenedor de desarrollo o el entorno alojado que mantiene el repositorio. Debe proporcionar el entorno de ejecución del lenguaje declarado, las herramientas de paquetes, el entorno de ejecución de contenedores, las bibliotecas nativas y todas las dependencias del proyecto. Al trabajar localmente: 1. Ejecuta el comando canónico de preparación. 2. Invoca la biblioteca o la herramienta de línea de comandos mediante el ejecutor de dependencias del repositorio. 3. Utiliza los scripts de mantenimiento documentados en vez de reproducir sus efectos a mano. 4. Confirma que estén presentes las dependencias nativas necesarias para detectar codificaciones, acceder al repositorio o trabajar con gramáticas. No consideres que una invocación improvisada que funciona localmente demuestra que el entorno compatible también pasará las comprobaciones. ## Añadir una extensión en orden alfabético y con muestras reales Al añadir una extensión de archivo a un lenguaje existente: 1. Actualiza la entrada autoritativa del lenguaje. 2. Mantén las listas de extensiones en el orden alfabético requerido, distinguiendo mayúsculas de minúsculas, con las mayúsculas antes que las minúsculas y la extensión principal en primer lugar. 3. Añade archivos de muestra representativos del uso real bajo el lenguaje correspondiente. 4. Si otro lenguaje comparte la extensión, proporciona al menos dos muestras y añade una heurística de desambiguación. 5. Añade o actualiza las pruebas de los metadatos y del comportamiento heurístico. No utilices ejemplos típicos de tutoriales, como programas triviales de saludo, como evidencia para el clasificador. Las muestras deben reflejar código real que el detector deba reconocer. ## Añadir un lenguaje nuevo con su gramática y un ID generado por script Un lenguaje nuevo requiere más que una etiqueta en el registro: 1. Añade la entrada del lenguaje, pero deja sin asignar su identificador generado. 2. Registra una gramática aprobada y compatible para el resaltado de sintaxis mediante la herramienta canónica de gramáticas. 3. Añade archivos de muestra representativos procedentes de fuentes originales verificables. 4. Ejecuta el script de generación de identificadores en vez de asignar uno manualmente. 5. Si alguna extensión es compartida, proporciona al menos dos muestras y añade reglas de desambiguación probadas. 6. Verifica conjuntamente los metadatos, el registro de la gramática, la clasificación y los cambios generados. Conserva las instrucciones del encabezado del registro, los requisitos de los campos y el orden que distingue mayúsculas de minúsculas. ## Escribir reglas regex probadas para distinguir lenguajes que comparten extensión Las heurísticas deben resolver ambigüedades reales sin generar falsos positivos amplios. - Busca la evidencia distintiva mínima que separe los lenguajes en conflicto. - Mantén cada patrón lineal respecto al tamaño de la entrada. - Evita construcciones vulnerables a ataques de denegación de servicio mediante expresiones regulares. - Utiliza únicamente la sintaxis compatible con el motor de expresiones regulares exigido por el repositorio. - Prueba casos positivos, casos del lenguaje competidor y casos cercanos al límite. - Ejecuta la validación cruzada del clasificador cuando un cambio de heurística o de muestra pueda modificar el comportamiento de detección. Todas las heurísticas deben tener pruebas. No es aceptable una regla que reconozca el objetivo pero también capture archivos no relacionados. ## Regenerar los archivos con los comandos de mantenimiento, sin editarlos a mano No edites a mano los registros generados, las declaraciones de módulos, el contenido de gramáticas incorporadas ni los archivos de licencias de gramáticas almacenados en caché. Utiliza el comando de mantenimiento responsable para añadir o sustituir una gramática y revisa todos los cambios generados que produzca. Antes de aceptar una gramática: - confirma que sea compatible con el formato de resaltado de sintaxis utilizado por el proyecto; - verifica que su licencia figure en la lista aprobada; - conserva la URL canónica de la fuente y el registro de la licencia; - ejecuta la validación específica de la gramática en el entorno de contenedor compatible. Si el resultado generado es incorrecto, corrige la entrada de origen o el flujo de generación en vez de aplicar un parche al resultado. ## Ejecutar la validación cruzada del clasificador y todas las pruebas Ejecuta primero las comprobaciones pertinentes más acotadas y después toda la validación obligatoria del repositorio: 1. Valida los metadatos modificados y su orden. 2. Ejecuta las pruebas de las muestras y heurísticas nuevas. 3. Ejecuta la validación cruzada del clasificador cuando puedan cambiar los límites de detección. 4. Ejecuta el conjunto completo de pruebas mediante el ejecutor canónico de dependencias. 5. Confirma que la integración continua supere las mismas etapas obligatorias. Revisa los fallos en busca de falsos positivos, desviaciones en archivos generados, dependencias nativas ausentes, datos de gramática no válidos y cambios imprevistos en lenguajes no relacionados. ## Mostrar pruebas de uso y licencias de las muestras antes del envío Antes de abrir una solicitud de contribución: - utiliza la plantilla proporcionada y elimina únicamente las secciones irrelevantes; - enlaza evidencias de búsqueda pública para cada extensión añadida, excluyendo las bifurcaciones; - muestra al menos 2000 archivos indexados para extensiones comunes, o 200 archivos para nombres que normalmente aparecen una vez por repositorio; - comprueba que exista una distribución razonable entre combinaciones distintas de usuarios y repositorios, teniendo en cuenta a los usuarios con una proporción inusualmente alta; - enlaza cada muestra con su fuente original, no con la bifurcación utilizada para la contribución; - indica por separado la licencia de cada muestra de código; - supera todas las pruebas obligatorias y las comprobaciones de integración continua; - mantén el cambio enfocado y no lo combines con refactorizaciones no relacionadas. Si falta algún requisito, no abras la solicitud. Explica qué evidencia, licencia, prueba o condición de alcance falta y qué debe completarse primero.