rizqirizqi/astroidal

¿Qué hace astroidal?

Astroidal es el mapa, puntuador y ayudante de revisión de código con IA. Dibuja el radio de explosión y puntúa lo que puedes probar. Mapea el cambio, búscalo en busca de errores reales y luego clasifica los hallazgos. El gráfico y la tabla viven en archivos. La respuesta en el chat es un breve resumen en prosa que una persona puede pegar.

El catálogo de errores está en references/review-lenses.md, al lado de este archivo. Léelo antes de juzgar un hallazgo. No está en .astroidal/.

No agregues Astroidal como dependencia. No edites package.json, lockfiles, pyproject.toml, go.mod ni Cargo.toml para instalarlo.

Ejecutarlo

Resuelve el comando en este orden:

1. astroidal si ya está en el PATH
2. npx --yes astroidal

Si el nombre del paquete no se puede descargar y el usuario señaló una copia local, ejecuta npx --yes <ruta-al-paquete-astroidal> o node <ruta>/dist/cli.js.

Instala la habilidad una vez por repositorio:

npx --yes astroidal init

Pasa --global para instalarla una vez para todos los repositorios de esta máquina:

npx --yes astroidal init --global

Una instalación global se actualiza cuando una versión más reciente de Astroidal ejecuta graph o rank, siempre que esos archivos de la habilidad sigan siendo los que Astroidal escribió. Una habilidad editada permanece en su lugar hasta init --force. Ejecuta init nuevamente para refrescar una instalación de proyecto.

Elegir el alcance

Ejecuta graph una vez. Lee la nota de alcance que imprime. Si ese alcance es incorrecto, vuelve a ejecutarlo una vez con la bandera a continuación. No lo vuelvas a ejecutar después.

Preguntar	Comando
Ediciones actuales, incluidos archivos sin seguimiento	npx --yes astroidal graph
Esta rama o su pull request, cuando el árbol de trabajo está sucio	npx --yes astroidal graph --base <rama-default>
Una rama de característica limpia	npx --yes astroidal graph
Números o URLs de pull requests	npx --yes astroidal graph --pr 12,18,24
Todos los pull requests abiertos	npx --yes astroidal graph --open
Pull requests abiertos por autor, etiqueta o base	npx --yes astroidal graph --open --author NOMBRE --label NOMBRE --base RAMA
El pull request actual y la pila debajo de él	npx --yes astroidal graph --stack
Un commit	npx --yes astroidal graph --commit SHA
Solo cambios staged	npx --yes astroidal graph --staged
Cambios unstaged y archivos sin seguimiento	npx --yes astroidal graph --unstaged

Un lote es un mapa fusionado. No revises los pull requests como informes separados.

GitHub

Llama a gh para lo que esta revisión aún necesite. El mapa ya hizo las lecturas locales primero, así que no enumeres los mismos archivos nuevamente, no vuelvas a obtener un diff que ya almacenó, ni consultes checks. Unas pocas llamadas específicas están bien, como gh pr view cuando falte un título, base o cuerpo. No hagas spam a gh, y no comentes en un pull request, lo apruebes ni solicites revisores.

GitLab

Llama a glab para lo que esta revisión aún necesite. El mapa ya hizo las lecturas locales primero, así que no enumeres los mismos archivos nuevamente, no vuelvas a obtener un diff que ya almacenó, ni consultes pipelines. Unas pocas llamadas específicas están bien, como glab mr view cuando falte un título, base o cuerpo. No hagas spam a glab, y no comentes en un merge request, lo apruebes ni solicites revisores.

Buscar errores

Lee, en orden:

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 al lado de esta habilidad

Aplica la puerta de entrada, la pasada de especificación y la pasada de estándares del catálogo. Luego aplica cada sección de lenguaje que coincida con un archivo en las líneas Agregadas. Omite las demás secciones de lenguaje.

Cubre cada ruta modificada en el mapa de errores. Comienza con la sección Líneas agregadas. Esa sección es el cambio, un bloque por pull request. Un extracto de símbolo puede estar en blanco cuando el diff se obtuvo de forma remota, y en una pila es solo la punta. Un extracto en blanco es contexto faltante, no un cambio vacío.

No te detengas después del primer archivo probable. Para cada bloque de código fuente que no sea de prueba en Líneas agregadas:

• Lee todo el bloque, incluidas las líneas debajo de él cuando el bloque dice que las líneas adicionales están en el archivo de evidencia.
• Verifica ese bloque contra el catálogo, no solo la clase que coincide con el nombre del archivo. Las cinco clases a continuación son el mínimo.
• Cuando un archivo enumera más de un pull request, revisa cada bloque. El cuerpo mapeado es solo la punta de la pila.
• Abre el archivo cuando el bloque no sea suficiente para confirmar o rechazar un error.
• Para cada símbolo modificado, inspecciona los llamadores y llamados de un salto que el mapa enumera cuando el cambio podría romperlos.

Busca especialmente una rama incorrecta, un valor falsy o vacío tratado como faltante, un error de desfase por uno o de zona horaria, un bloqueo o estado que impida un reintento después de una falla, una URL o consulta construida por concatenación, una verificación de autorización que use la identidad incorrecta y un contrato que los llamadores de un salto aún usen de la manera antigua. Una puntuación de alto impacto no es un hallazgo y no excusa saltarse un bloque.

Busca en todas estas clases:

• Lógica y casos límite: ramas incorrectas, desfase por uno, errores tragados, caídas por null
• Pérdida de datos y estado: migraciones, condiciones de carrera, escrituras parciales, caché obsoleto
• Contratos rotos: API, tipos, rutas, comportamiento exportado, desajuste de esquema
• Errores de seguridad: brechas de autorización, inyección, secretos, límites de confianza inseguros
• Errores de flujo UX: puntos muertos, estados de error, vacío o carga faltantes, navegación rota

Busca problemas importantes. Las pistas en los paquetes son sugerencias, no hallazgos. Un olor a código, un archivo largo, una prueba faltante o un aumento de dependencia es un hallazgo solo cuando la puerta de entrada del catálogo pasa. Ignora formato, nombres, comentarios, elogios, preguntas y refactorizaciones que no nombren una falla concreta.

Escribir hallazgos

Escribe .astroidal/findings.json:

{
  "findings": [
    {
      "pr": 12,
      "severity": "high",
      "description": "Qué se rompe, en una o dos oraciones.",
      "path": "src/auth.ts",
      "line": 12,
      "quote": "la línea exacta copiada del archivo",
      "recommendation": "El cambio específico que elimina el error.",
      "category": "security"
    }
  ]
}

severity es critical, high o medium, usando la puerta de entrada del catálogo. critical es una caída, pérdida de datos, bypass de autorización, inyección o exposición de secretos en una ruta que los usuarios usan. high es un resultado incorrecto realista, una escritura perdida, una condición de carrera o un contrato roto. medium es un caso límite realista que falla. quote es una línea exacta copiada de un bloque de líneas agregadas, del archivo mapeado o de su vecino de un salto. Establece pr al pull request que introdujo esa línea, u omítelo para un cambio local.

Di qué se rompe, nombra el símbolo y da el cambio que elimina el error. Para seguridad y arquitectura, di por qué ese cambio se sostiene. No evadas, no repitas la línea citada ni presentes una pregunta. Un arreglo findings vacío es válido solo después de que las líneas agregadas de cada archivo fuente que no sea de prueba hayan sido verificadas contra el catálogo y ninguna de ellas contenga un error importante.

Cuando los archivos modificados pertenezcan juntos por una razón que el directorio ya no muestre, nombra ese grupo. El gráfico dibuja un directorio por sí mismo y dibuja una importación como una línea. Un grupo es para un flujo, una característica o un contrato compartido que los cruza.

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

Usa un nombre corto y al menos dos rutas mapeadas. Omite groups cuando nada adicional pertenezca junto.

Luego ejecuta:

npx --yes astroidal rank

Si rank descarta un hallazgo porque la cita o la ruta son incorrectas, corrige ese hallazgo una vez y vuelve a ejecutar rank. No inventes un error de reemplazo para mantener el conteo alto. No ejecutes rank una tercera vez.

Responder

Escribe un breve resumen en prosa en el chat. Abre con una línea que la persona pueda pegar: Astroidal {puntuación} · Aprobado o Astroidal {puntuación} · Arreglar primero. Luego nombra los problemas de mayor severidad y las dos rutas de salida: .astroidal/review.md y .astroidal/constellation.html. No pegues la tabla de hallazgos. No recrees el gráfico. El humano aún decide si fusionar.