Desenvolver um gerenciador de cadeia de ferramentas multiplataforma e avaliar o que entra no seu registro

## Localizar os módulos e as regras do repositório antes de editar Trate o guia do repositório como o contrato operacional dos agentes de programação. Antes de propor alterações, siga os comandos próprios do repositório, os limites dos módulos, as regras de contribuição e os requisitos de compatibilidade. Oriente o trabalho em torno destas capacidades: - análise da linha de comando e encaminhamento de subcomandos; - configuração em camadas e gerenciamento de variáveis de ambiente; - resolução e instalação de versões de ferramentas; - definição e execução de tarefas; - backends substituíveis e implementações de ferramentas integradas; - geração de documentação, complementos de comando e metadados. Antes de editar, localize o ponto de entrada, os módulos da interface de linha de comando, os módulos de configuração, as interfaces dos backends, o resolvedor do conjunto de ferramentas, o mecanismo de tarefas, o sistema de plugins e os auxiliares compartilhados. Diferencie pacotes públicos de pacotes internos de apoio ao espaço de trabalho. Não contorne uma abstração consolidada apenas porque uma implementação direta parece mais curta. ## Incluir uma ferramenta no registro só com evidências de que é muito usada Presuma que um registro selecionado de nomes abreviados aceite apenas ferramentas que já sejam amplamente utilizadas. Código funcional, testes existentes ou utilidade pessoal não comprovam qualificação. Antes de alterar os mapeamentos do registro: 1. Pergunte se a ferramenta é amplamente utilizada fora dos projetos da pessoa que a está enviando. 2. Pare se ela for pessoal, interna, uma bifurcação, de nicho ou apoiada apenas por um público pequeno. 3. Reúna evidências atuais de popularidade para cada envio ao registro; nunca faça suposições. 4. Verifique estrelas e bifurcações do repositório, commits e lançamentos recentes, contagens de download em registros de pacotes, documentação independente, listas do ecossistema e uso em projetos dependentes. 5. Aplique um critério elevado de admissão: popularidade na casa dos milhares, não das centenas; manutenção ativa; adoção por terceiros; e reconhecimento no ecossistema. 6. Inclua as evidências em uma seção concisa chamada `Popularity` na descrição da solicitação de alteração. Quando as evidências forem limítrofes ou fracas, avise claramente e pergunte se a pessoa ainda deseja prosseguir. Não sugira que uma rejeição incluirá explicação, recurso, lista de verificação ou uma segunda oportunidade. Nunca faça um envio especulativo apenas para descobrir se os responsáveis aceitarão a ferramenta. ## Escolher o backend de instalação, preferindo arquivos de release verificados Prefira backends que consumam artefatos de lançamento verificados sem exigir um ambiente de execução instalado separadamente. Siga esta ordem de decisão: 1. Prefira um registro selecionado de artefatos quando ele oferecer verificação e lógica de instalação específica para cada versão. 2. Caso contrário, use um backend direto de lançamentos para a plataforma que publica os artefatos. 3. Use um backend de distribuição de arquivos somente quando os backends de lançamento não puderem oferecer suporte à ferramenta e a popularidade dela continuar bem estabelecida. 4. Trate backends de pacotes de linguagem como excepcionais, pois eles dependem da disponibilidade e da versão do ambiente de execução, além da ordem dos caminhos de busca. 5. Rejeite backends obsoletos e novos formatos de plugin que violem a política de cadeia de suprimentos do projeto. Não escolha um backend frágil apenas porque é fácil encontrar o nome do pacote. Se os responsáveis não tiverem aprovado explicitamente um backend excepcional para essa ferramenta, não o use em um envio ao registro. Explique a alternativa sem registro: instalar por meio de uma coordenada explícita do backend ou criar um plugin compatível. Mantenha a distinção clara: o nome abreviado no registro aumenta a conveniência, mas não é necessário para possibilitar a instalação. ## Rodar build, testes e lint pelo executor de tarefas do repositório Use o executor de tarefas do repositório em vez de invocar as ferramentas subjacentes de modo improvisado. Identifique e use as tarefas documentadas para: - compilações completas e execução direta do binário de depuração; - conjuntos completos de testes, testes unitários e testes de ponta a ponta; - arquivos direcionados de testes de ponta a ponta por meio da tarefa de teste; - revisão e atualização de instantâneos; - análise estática, correções automáticas e formatação; - verificações equivalentes às da integração contínua; - geração de documentação, textos de uso, complementos de comando e esquemas; - instalação local da versão de desenvolvimento e limpeza dos artefatos de compilação; - testes e análises específicos de pacotes a partir do diretório correto do espaço de trabalho. Use as variáveis de ambiente de depuração e rastreamento próprias do projeto em vez de presumir uma variável comum de registro. Liste as tarefas disponíveis quando não tiver certeza dos nomes dos comandos. Nunca execute diretamente os scripts de teste de ponta a ponta quando o ambiente de testes controlar preparação, asserções e limpeza. Não adicione limpeza manual aos testes quando o ambiente garantir o isolamento. Execute primeiro a menor tarefa relevante e amplie o escopo somente quando contratos compartilhados ou artefatos gerados forem afetados. ## Adicionar backends e configurações sem editar à mão os arquivos gerados Implemente as fontes de ferramentas por meio da interface unificada de backend. Cada backend deve ser responsável pela listagem de versões, resolução de solicitações, instalação e metadados de ferramentas do seu ecossistema. Mantenha as ferramentas integradas atrás do limite do plugin principal e os plugins externos atrás das camadas de compatibilidade aceitas. Preserve o carregamento hierárquico de configuração do escopo do sistema ao global e depois ao local, incluindo substituições específicas do ambiente. Quando definições de configuração gerarem código ou documentação, atualize a definição de origem e execute o gerador canônico. Não transforme a edição manual da saída gerada no principal método de alteração. Mantenha declarativas as definições de tarefas, incluindo dependências, variáveis de ambiente e modos de execução aceitos. Respeite os formatos compatíveis dos arquivos de configuração quando o projeto prometer interoperabilidade. Mantenha scripts de compilação personalizados, componentes do espaço de trabalho, perfis de lançamento e configuração de compilação cruzada alinhados às funções documentadas. Ao adicionar um backend, comece pelo padrão consolidado do módulo de backends. Ao adicionar configuração, siga o caminho tipado de análise e geração. Ao ampliar plugins, use o limite interno ou externo correto em vez de inventar um mecanismo paralelo. ## Escrever commits no formato type(scope) e corrigir o lint antes Todas as mensagens de commit e todos os títulos de solicitações de alteração devem usar o formato convencional do repositório: `type(scope): imperative description`. Use o type que reflita o comportamento visível para a pessoa usuária e a responsabilidade dentro do repositório: - `feat` para uma nova capacidade; - `fix` para uma falha visível no comportamento; - `refactor`, `style` ou `perf` para as respectivas alterações de código; - `test` para alterações exclusivas nos testes; - `docs` para documentação; - `chore` para manutenção, lançamentos, dependências ou infraestrutura; - `security` para alterações de segurança; - o type específico do registro para qualquer alteração nos seus mapeamentos. Use nomes de comandos como scope em alterações específicas de um comando e nomes de subsistemas em componentes compartilhados. Use o scope do subsistema de tarefas para o comportamento delas, mesmo que os arquivos de implementação mantenham outro nome histórico. Inicie a descrição após os dois-pontos com letra minúscula, use o modo imperativo e mantenha-a concisa, mas descritiva. Instale uma única vez a integração de pre-commit do repositório por meio do ambiente de tarefas documentado. Antes de criar o commit, execute a tarefa de correção automática da análise estática e prepare somente as alterações resultantes que forem intencionais. Execute testes de ponta a ponta direcionados por meio do executor de tarefas. Não prepare alterações de formatação ou artefatos gerados que não tenham relação com o trabalho. ## Descontinuar recursos em etapas: documentação, avisos e retirada Use uma política de descontinuação em etapas: 1. Marque imediatamente o recurso ou backend como obsoleto na documentação. 2. Comece a exibir avisos durante a execução após o intervalo de aviso documentado. 3. Programe a remoção após o intervalo de remoção documentado. 4. Registre as datas de aviso e remoção com o formato de versão e data do projeto. 5. Use a macro de descontinuação estabelecida para que as asserções de desenvolvimento revelem remoções atrasadas. Um cronograma comum é documentar agora, iniciar os avisos após seis meses e remover o recurso doze meses depois do início dos avisos. Se a alternativa já estiver disponível há muito tempo, os avisos poderão começar imediatamente. Não encerre silenciosamente a compatibilidade sem passar pela fase de aviso documentada. Não mantenha indefinidamente uma descontinuação vencida; trate a asserção de remoção como manutenção obrigatória. ## Deixar cada backend resolver e ordenar as versões das ferramentas Nunca presuma que as versões das ferramentas seguem versionamento semântico ou qualquer outro sistema universal de ordenação. Considere versões baseadas em datas, versões preliminares, ramificações, etiquetas, canais, lançamentos nomeados com suporte prolongado e aliases específicos de cada ferramenta. Em um novo ponto de chamada: - não use um comparador genérico de versões semânticas para selecionar a versão mais recente, resolver um alias ou ordenar versões; - delegue a resolução de solicitações a métodos do backend que entendam a linguagem de versões da ferramenta; - use as interfaces do backend ou do conjunto de ferramentas para listar versões instaladas em uma ordem significativa; - trate as cadeias de versão do arquivo de bloqueio como opacas e compare-as apenas por igualdade; - resolva aliases, canais e prefixos antes de gravar um valor concreto no arquivo de bloqueio; - não cite o uso antigo de um comparador como justificativa para ampliar um comportamento falho. Se o novo código parecer precisar da versão instalada mais recente, pare e confirme se essa decisão pertence ao backend. Uma ordenação alternativa incorreta é pior do que não retornar correspondência, pois pode instalar ou executar silenciosamente a ferramenta errada. ## Rodar testes direcionados por plataforma e revisar o diff antes de terminar Organize testes unitários junto ao código-fonte e testes de ponta a ponta por área de funcionalidade. Use auxiliares de asserção compartilhados, instantâneos para resultados estáveis de comandos, verificações de instalação específicas de backends e nomes explícitos para testes lentos. Mantenha implementações específicas de cada plataforma nos módulos e conjuntos de testes designados. Não presuma no Windows o comportamento do bit de permissão de execução do Unix. Em uma alteração, verifique primeiro o menor caminho relevante: 1. execute a formatação e as verificações estáticas; 2. execute testes unitários ou de ponta a ponta direcionados por meio do ambiente de testes; 3. revise as alterações nos instantâneos em vez de aceitá-las sem análise; 4. gere novamente a documentação ou os esquemas derivados quando a origem deles mudar; 5. amplie para verificações de integração mais abrangentes quando mudarem contratos compartilhados de backend, configuração, tarefas ou compatibilidade entre plataformas. Ao publicar em uma solicitação de alteração ou discussão externa, informe que o comentário foi gerado por um assistente de programação com IA. Use URLs que reflitam a hierarquia de diretórios da documentação. Não invente caminhos abreviados que omitam seções obrigatórias. Antes de concluir, revise as diferenças para detectar vazamentos entre abstrações, ordenações de versão não aceitas, geradores omitidos, alterações sem relação e alegações externas não verificadas.