rizqirizqi/astroidal

O que astroidal faz?

Astroidal é o mapa de revisão, pontuador e assistente de revisão de código com IA. Ele desenha o raio de impacto e pontua o que você pode provar. Mapeie a alteração, procure por bugs reais e classifique as descobertas. O gráfico e a tabela ficam em arquivos. A resposta no chat é um breve resumo em prosa que uma pessoa pode colar.

O catálogo de bugs está em references/review-lenses.md, ao lado deste arquivo. Leia-o antes de julgar uma descoberta. Ele não está em .astroidal/.

Não adicione Astroidal como uma dependência. Não edite package.json, lockfiles, pyproject.toml, go.mod ou Cargo.toml para instalá-lo.

Execute-o

Resolva o comando nesta ordem:

1. astroidal se já estiver no PATH
2. npx --yes astroidal

Se o nome do pacote não puder ser baixado e o usuário apontou para um checkout local, execute npx --yes <caminho-para-o-pacote-astroidal> ou node <caminho>/dist/cli.js.

Instale a habilidade uma vez por repositório:

npx --yes astroidal init

Use --global para instalá-la uma vez para todos os repositórios nesta máquina:

npx --yes astroidal init --global

Uma instalação global é atualizada quando um Astroidal mais novo executa graph ou rank, desde que esses arquivos de habilidade ainda sejam os que o Astroidal escreveu. Uma habilidade editada permanece no lugar até init --force. Execute init novamente para atualizar uma instalação de projeto.

Escolha o escopo

Execute graph uma vez. Leia a nota de escopo que ele imprime. Se esse escopo estiver errado, execute novamente uma vez com a flag abaixo. Não execute novamente depois disso.

Pergunta	Comando
Edições atuais, incluindo arquivos não rastreados	npx --yes astroidal graph
Este branch ou seu pull request, quando a árvore de trabalho está suja	npx --yes astroidal graph --base <branch-padrão>
Um branch de funcionalidade limpo	npx --yes astroidal graph
Números ou URLs de pull requests	npx --yes astroidal graph --pr 12,18,24
Todos os pull requests abertos	npx --yes astroidal graph --open
Pull requests abertos por autor, label ou base	npx --yes astroidal graph --open --author NOME --label NOME --base BRANCH
O pull request atual e a pilha abaixo dele	npx --yes astroidal graph --stack
Um commit	npx --yes astroidal graph --commit SHA
Apenas alterações staged	npx --yes astroidal graph --staged
Alterações unstaged e arquivos não rastreados	npx --yes astroidal graph --unstaged

Um lote é um único mapa mesclado. Não revise os pull requests como relatórios separados.

GitHub

Chame gh para o que esta revisão ainda precisar. O mapa já fez as leituras locais primeiro, então não liste os mesmos arquivos novamente, não busque novamente um diff que já foi armazenado, nem consulte verificações. Algumas chamadas direcionadas são aceitáveis, como gh pr view quando um título, base ou corpo estiver faltando. Não encha gh de chamadas e não comente em um pull request, aprove-o ou solicite revisores.

GitLab

Chame glab para o que esta revisão ainda precisar. O mapa já fez as leituras locais primeiro, então não liste os mesmos arquivos novamente, não busque novamente um diff que já foi armazenado, nem consulte pipelines. Algumas chamadas direcionadas são aceitáveis, como glab mr view quando um título, base ou corpo estiver faltando. Não encha glab de chamadas e não comente em um merge request, aprove-o ou solicite revisores.

Procure por bugs

Leia, em ordem:

1. .astroidal/packets/bug-map.md
2. .astroidal/packets/architecture.md
3. .astroidal/packets/security.md
4. .astroidal/packets/performance.md
5. .astroidal/packets/ux.md
6. .astroidal/packets/correctness.md
7. references/review-lenses.md ao lado desta habilidade

Aplique o gate, a passagem de especificação e a passagem de padrões do catálogo. Em seguida, aplique cada seção de linguagem que corresponde a um arquivo nas linhas Adicionadas. Pule as outras seções de linguagem.

Cubra cada caminho alterado no mapa de bugs. Comece pela seção Linhas Adicionadas. Essa seção é a alteração, um bloco por pull request. Um trecho de símbolo pode estar em branco quando o diff foi buscado remotamente e, em uma pilha, é apenas a ponta. Um trecho em branco é contexto faltando, não uma alteração vazia.

Não pare após o primeiro arquivo provável. Para cada bloco de código fonte que não seja de teste nas Linhas Adicionadas:

• Leia o bloco inteiro, incluindo as linhas abaixo dele quando o bloco disser que mais linhas estão no arquivo de evidências.
• Verifique esse bloco contra o catálogo, não apenas a classe que corresponde ao nome do arquivo. As cinco classes abaixo são o mínimo.
• Quando um arquivo lista mais de um pull request, revise cada bloco. O corpo mapeado é apenas a ponta da pilha.
• Abra o arquivo quando o bloco não for suficiente para confirmar ou rejeitar um bug.
• Para cada símbolo alterado, inspecione os chamadores e chamados de um salto que o mapa lista quando a alteração pode quebrá-los.

Procure especialmente por: um branch errado, um valor falso ou vazio tratado como ausente, um erro de off-by-one ou fuso horário, um bloqueio ou status que impede uma nova tentativa após uma falha, uma URL ou consulta construída por concatenação, uma verificação de autorização que usa a identidade errada e um contrato que os chamadores de um salto ainda usam da maneira antiga. Uma pontuação de alto impacto não é uma descoberta e não desculpa pular um bloco.

Pesquise todas estas classes:

• Lógica e casos limite: branches errados, off-by-one, erros engolidos, crashes por null
• Perda de dados e estado: migrações, condições de corrida, escritas parciais, cache obsoleto
• Contratos quebrados: API, tipos, rotas, comportamento exportado, incompatibilidade de esquema
• Bugs de segurança: lacunas de autorização, injeção, segredos, limites de confiança inseguros
• Bugs de fluxo de UX: becos sem saída, estados de erro, vazio ou carregamento ausentes, navegação quebrada

Procure por problemas importantes. Leads nos pacotes são dicas, não descobertas. Um code smell, um arquivo longo, um teste ausente ou um aumento de dependência é uma descoberta apenas quando o gate do catálogo passa. Ignore formatação, nomenclatura, comentários, elogios, perguntas e refatorações que não nomeiam uma falha concreta.

Escreva descobertas

Escreva .astroidal/findings.json:

{
  "findings": [
    {
      "pr": 12,
      "severity": "high",
      "description": "O que quebra, em uma ou duas frases.",
      "path": "src/auth.ts",
      "line": 12,
      "quote": "a linha exata copiada do arquivo",
      "recommendation": "A alteração específica que remove o bug.",
      "category": "security"
    }
  ]
}

severity é critical, high, ou medium, usando o gate do catálogo. critical é um crash, perda de dados, bypass de autorização, injeção ou exposição de segredo em um caminho que os usuários acessam. high é um resultado errado realista, escrita perdida, condição de corrida ou contrato quebrado. medium é um caso limite realista que falha. quote é uma linha exata copiada de um bloco de linhas adicionadas, do arquivo mapeado ou de seu vizinho de um salto. Defina pr como o pull request que introduziu essa linha ou omita-o para uma alteração local.

Diga o que quebra, nomeie o símbolo e forneça a alteração que remove o bug. Para segurança e arquitetura, diga por que essa alteração se mantém. Não hesite, não repita a linha citada nem registre uma pergunta. Um array findings vazio é válido somente depois que as linhas adicionadas de cada arquivo de código fonte que não seja de teste foram verificadas contra o catálogo e nenhuma delas contém um bug importante.

Quando os arquivos alterados pertencem juntos por uma razão que o diretório já não mostra, nomeie esse grupo. O gráfico desenha um diretório por conta própria e desenha uma importação como uma linha. Um grupo é para um fluxo, uma funcionalidade ou um contrato compartilhado que cruza esses limites.

{
  "findings": [],
  "groups": [
    {
      "name": "Links de pagamento",
      "paths": ["apps/admin/lib/whatsapp.ts", "apps/admin/lib/proxied-link.ts"]
    }
  ]
}

Use um nome curto e pelo menos dois caminhos mapeados. Omita groups quando nada extra pertencer junto.

Em seguida, execute:

npx --yes astroidal rank

Se o rank descartar uma descoberta porque a citação ou o caminho estão errados, corrija essa descoberta uma vez e classifique novamente. Não invente um bug substituto para manter a contagem. Não classifique uma terceira vez.

Responda

Escreva um breve resumo em prosa no chat. Abra com uma linha que a pessoa possa colar: Astroidal {pontuação} · Passou ou Astroidal {pontuação} · Corrija primeiro. Em seguida, nomeie os problemas de maior gravidade e os dois caminhos de saída: .astroidal/review.md e .astroidal/constellation.html. Não cole a tabela de descobertas. Não recrie o gráfico. O humano ainda decide se vai fazer o merge.