recurspec

RecurSpec é um pacote Node.js em estágio inicial, com licença MIT, que testa caminhos de recuperação em ferramentas de linha de comando. Enquanto um teste convencional pode apenas afirmar que uma mensagem de erro foi impressa, o RecurSpec verifica se o comando que a mensagem sugere realmente corrige o problema, para que os usuários realmente consigam prosseguir. Como funciona Um caso de teste é descrito declarativamente em um arquivo recurspec.yml. Cada caso declara o comando a ser executado, a falha esperada (por exemplo, um código de saída diferente de zero e uma substring no stderr), de onde vem a instrução de recuperação e uma etapa de verificação. A verificação pode executar novamente o comando original e exigir um código de saída zero, para que a ferramenta confirme que o loop de recuperação se fecha, em vez de apenas que o conselho está presente. Primeiros passos O projeto requer Node.js 22 ou posterior e pnpm. Ele é instalado como uma dependência de desenvolvimento e, em seguida, utilizado através de três comandos principais: uma etapa de init que escreve uma configuração inicial contendo um exemplo executável em Node.js, uma etapa de validate e uma etapa de test. A demonstração incluída mistura deliberadamente caminhos de recuperação bem-sucedidos e quebrados. Interface de linha de comando A CLI expõe os comandos test, validate, init, explain e discover. O comando test suporta opções para selecionar um caso ou tag, escolher um formato de relatório (human, json, junit ou markdown), saída detalhada (verbose), comportamento fail-fast, um seed e um dry run. Os códigos de saída são definidos como 0 para todos aprovados, 1 para um contrato falho e 2 para erros de configuração ou de uso. Os relatores JSON, JUnit e Markdown são destinados a pipelines de CI e comentários de pull-request. Uma API programática também está disponível através de runRecurSpec. O que ele detecta A ferramenta visa incompatibilidades entre uma mensagem de erro e suas instruções: comandos sugeridos que não existem mais, etapas de recuperação incompletas, comandos que têm sucesso sem resolver o problema original, conselhos que levam a um erro posterior, loops de instrução e instruções que são ambíguas ou inseguras. Recuperação de tentativa e de objetivo Dois formatos de recuperação são suportados. Na recuperação estilo retry, a remoção de um bloqueador permite que o comando original tenha sucesso em uma segunda tentativa. Na recuperação de objetivo (goal recovery), o comando sugerido substitui inteiramente a operação que falhou, de modo que o objetivo do usuário seja atingido, mesmo que a execução do comando original ainda falhasse. O README observa que o trabalho em casos do Cargo evidenciou essa distinção e levou à verificação baseada em objetivos. Compatibilidade com o mundo real A suíte de compatibilidade inclui casos extraídos do Git, Cargo e npm, cobrindo situações como identidade do Git ausente, exclusão de branch, conselhos de pull divergentes, um diretório de projeto Cargo existente e um script npm ausente. Os resultados incluem conselhos ambíguos (múltiplos comandos exclusivos ou obrigatórios), recuperação de objetivo e mensagens apenas informativas que são corretamente ignoradas. Ferramentas ausentes são ignoradas quando a suíte é executada. Modelo de segurança Os comandos de recuperação são analisados e verificados antes da execução. O encadeamento de shell, redirecionamento, substituição de comando e comandos destrutivos conhecidos são bloqueados por padrão, e cada caso é executado em um espaço de trabalho temporário isolado. O README é explícito que o backend local não impõe sandboxing de rede ao nível do SO, portanto, uma configuração deny-network permanece consultiva até que exista um backend de container. Limitações e status A documentação lista três limitações: ausência de isolamento de rede ao nível do SO no backend local, a necessidade de entrada padrão roteirizada ao testar programas TTY interativos (o suporte total a PTY é um trabalho futuro) e a dependência de ferramentas que imprimam conselhos pesquisáveis (greppable), com conselhos ambíguos ou ausentes sendo relatados em vez de presumidos. O RecurSpec é descrito como estando em estágio inicial, e tanto a configuração quanto a API pública podem mudar antes de um lançamento 1.0. Documentações separadas cobrem configuração, extração, segurança, relatores e descoberta.