Adicionar extensões de arquivo ou novas linguagens a um repositório de detecção de linguagens

## Identificar quais arquivos e ferramentas cuidam de cada parte da detecção Antes de editar, identifique quais arquivos e ferramentas controlam cada parte da detecção de linguagens: - o cadastro de linguagens para nomes, extensões, nomes de arquivos e propriedades da linguagem; - as regras heurísticas e sua implementação para arquivos ambíguos; - o classificador estatístico e seu corpus de amostras reais; - o cadastro de gramáticas usado para realce de sintaxe; - as fontes de gramáticas incorporadas e os dados de licença armazenados em cache; - os scripts de manutenção, testes e pontos de entrada da integração contínua. Trate essas áreas como contratos coordenados. Uma alteração de metadados pode exigir amostras, heurísticas, identificadores gerados, dados de gramática, testes e evidências, em vez de uma única edição isolada. ## Preparar o projeto no contêiner de desenvolvimento e usar seus scripts Quando disponível, prefira o contêiner de desenvolvimento ou o ambiente hospedado mantido pelo repositório. Ele deve fornecer o runtime da linguagem declarado, as ferramentas de pacotes, o runtime de contêiner, as bibliotecas nativas e todas as dependências do projeto. Ao trabalhar localmente: 1. Execute o comando oficial de preparação. 2. Invoque a biblioteca ou a ferramenta de linha de comando por meio do executor de dependências do repositório. 3. Use os scripts de manutenção documentados em vez de reproduzir seus efeitos manualmente. 4. Confirme a presença das dependências nativas necessárias para detectar codificação, acessar o repositório ou trabalhar com gramáticas. Não trate uma invocação improvisada que funcionou localmente como prova de que o ambiente com suporte também passará nas verificações. ## Adicionar uma extensão em ordem alfabética e com amostras reais Ao adicionar uma extensão de arquivo a uma linguagem existente: 1. Atualize a entrada oficial da linguagem. 2. Mantenha as listas de extensões na ordem alfabética exigida, diferenciando maiúsculas de minúsculas, com maiúsculas antes de minúsculas e a extensão principal em primeiro lugar. 3. Adicione arquivos de amostra representativos do uso real sob a linguagem responsável. 4. Se outra linguagem compartilhar a extensão, forneça pelo menos duas amostras e adicione uma heurística de desambiguação. 5. Adicione ou atualize testes para os metadados e para o comportamento da heurística. Não use exemplos comuns de tutoriais, como programas triviais de saudação, como evidência para o classificador. As amostras devem refletir código real que o detector deve reconhecer. ## Adicionar uma nova linguagem com gramática e um ID gerado por script Uma nova linguagem exige mais do que um rótulo no cadastro: 1. Adicione a entrada da linguagem, mas deixe seu identificador gerado sem definição. 2. Cadastre uma gramática aprovada e compatível para realce de sintaxe por meio da ferramenta oficial de gramáticas. 3. Adicione arquivos de amostra representativos de fontes originais verificáveis. 4. Execute o script de geração de identificadores em vez de atribuir um identificador manualmente. 5. Se qualquer extensão for compartilhada, forneça pelo menos duas amostras e adicione regras de desambiguação testadas. 6. Verifique em conjunto os metadados, o cadastro da gramática, a classificação e as alterações geradas. Mantenha intactas as orientações do cabeçalho do cadastro, os requisitos dos campos e a ordenação que diferencia maiúsculas de minúsculas. ## Escrever regras regex testadas para distinguir linguagens com a mesma extensão As heurísticas devem resolver ambiguidades reais sem criar falsos positivos amplos. - Busque a menor evidência distintiva que separe as linguagens concorrentes. - Mantenha cada padrão linear em relação ao tamanho da entrada. - Evite estruturas vulneráveis a ataques de negação de serviço por expressões regulares. - Use somente a sintaxe aceita pelo mecanismo de expressões regulares exigido pelo repositório. - Teste casos positivos, casos da linguagem concorrente e casos próximos do limite. - Execute a validação cruzada do classificador quando uma alteração de heurística ou amostra puder mudar o comportamento da detecção. Toda heurística deve ter testes. Uma regra que reconhece o alvo, mas também captura arquivos sem relação, não é aceitável. ## Regenerar os arquivos com os comandos de manutenção, sem editá-los à mão Não edite manualmente cadastros gerados, declarações de módulos, conteúdo de gramáticas incorporadas ou arquivos de licença de gramáticas armazenados em cache. Use o comando de manutenção responsável para adicionar ou substituir uma gramática e revise todas as alterações que ele gerar. Antes de aceitar uma gramática: - confirme a compatibilidade com o formato de realce de sintaxe usado pelo projeto; - verifique se a licença está na lista aprovada; - preserve a URL oficial da fonte e o registro da licença; - execute a validação específica da gramática no ambiente de contêiner com suporte. Se o resultado gerado estiver incorreto, corrija a entrada de origem ou o fluxo de geração em vez de remendar o resultado. ## Rodar a validação cruzada do classificador e todos os testes Execute primeiro as verificações relevantes mais restritas e depois toda a validação obrigatória do repositório: 1. Valide os metadados alterados e sua ordenação. 2. Execute os testes das novas amostras e heurísticas. 3. Execute a validação cruzada do classificador quando os limites de detecção puderem mudar. 4. Execute o conjunto completo de testes por meio do executor oficial de dependências. 5. Confirme que a integração contínua passa pelas mesmas etapas obrigatórias. Analise as falhas em busca de falsos positivos, desvios em arquivos gerados, dependências nativas ausentes, dados de gramática inválidos e alterações não intencionais em linguagens sem relação. ## Mostrar evidências de uso e licenças das amostras antes do envio Antes de abrir uma solicitação de contribuição: - use o modelo fornecido e remova somente as seções irrelevantes; - vincule evidências de pesquisa pública para cada extensão adicionada, excluindo bifurcações; - apresente pelo menos 2000 arquivos indexados para extensões comuns ou 200 arquivos para nomes que normalmente aparecem uma vez por repositório; - confira se há distribuição razoável entre diferentes combinações de usuários e repositórios, considerando usuários com participação anormalmente alta; - vincule cada amostra à fonte original, não à bifurcação usada para a contribuição; - informe individualmente a licença de cada amostra de código; - passe em todos os testes obrigatórios e verificações de integração contínua; - mantenha a alteração focada e não a combine com refatorações sem relação. Se algum requisito não for atendido, não abra a solicitação. Explique qual evidência, licença, teste ou condição de escopo está faltando e o que precisa ser concluído primeiro.