rizqirizqi/astroidal

Que fait astroidal ?

Astroidal est la carte, le score et l’assistant de revue de code IA. Il dessine le rayon d’explosion et note ce que vous pouvez prouver. Cartographiez le changement, cherchez les vrais bugs, puis classez les résultats. Le graphique et le tableau vivent dans des fichiers. La réponse dans le chat est un court résumé en prose qu’une personne peut copier-coller.

Le catalogue de bugs se trouve dans references/review-lenses.md, à côté de ce fichier. Lisez-le avant de juger une découverte. Il n’est pas dans .astroidal/.

N’ajoutez pas Astroidal comme dépendance. Ne modifiez pas package.json, les fichiers de verrouillage, pyproject.toml, go.mod ou Cargo.toml pour l’installer.

Exécution

Résolvez la commande dans cet ordre :

1. astroidal s’il est déjà dans le PATH
2. npx --yes astroidal

Si le nom du paquet ne peut pas être téléchargé et que l’utilisateur a indiqué un checkout local, exécutez npx --yes <chemin-vers-le-paquet-astroidal> ou node <chemin>/dist/cli.js.

Installez la compétence une fois par dépôt :

npx --yes astroidal init

Passez --global pour l’installer une fois pour tous les dépôts de cette machine :

npx --yes astroidal init --global

Une installation globale se met à jour lorsqu’un Astroidal plus récent exécute graph ou rank, tant que ces fichiers de compétence sont toujours ceux qu’Astroidal a écrits. Une compétence modifiée reste en place jusqu’à init --force. Exécutez init à nouveau pour rafraîchir une installation de projet.

Choisir la portée

Exécutez graph une fois. Lisez la note de portée qu’il affiche. Si cette portée est incorrecte, relancez une fois avec le drapeau ci-dessous. Ne relancez pas après cela.

Demande	Commande
Modifications en cours, y compris les fichiers non suivis	npx --yes astroidal graph
Cette branche ou sa pull request, lorsque l’arbre de travail est sale	npx --yes astroidal graph --base <branche-par-défaut>
Une branche de fonctionnalité propre	npx --yes astroidal graph
Numéros ou URLs de pull requests	npx --yes astroidal graph --pr 12,18,24
Toutes les pull requests ouvertes	npx --yes astroidal graph --open
Pull requests ouvertes par auteur, label ou base	npx --yes astroidal graph --open --author NOM --label LABEL --base BRANCHE
La pull request actuelle et la pile en dessous	npx --yes astroidal graph --stack
Un commit	npx --yes astroidal graph --commit SHA
Modifications staging uniquement	npx --yes astroidal graph --staged
Modifications unstaging et fichiers non suivis	npx --yes astroidal graph --unstaged

Un lot est une carte unique fusionnée. Ne révisez pas les pull requests comme des rapports séparés.

GitHub

Appelez gh pour ce dont cette revue a encore besoin. La carte a déjà effectué les lectures locales en premier, donc ne listez pas les mêmes fichiers, ne récupérez pas un diff déjà stocké, et ne sondez pas les vérifications. Quelques appels ciblés sont acceptables, comme gh pr view lorsqu’un titre, une base ou un corps manque. Ne spammez pas gh, et ne commentez pas une pull request, ne l’approuvez pas et ne demandez pas de relecteurs.

GitLab

Appelez glab pour ce dont cette revue a encore besoin. La carte a déjà effectué les lectures locales en premier, donc ne listez pas les mêmes fichiers, ne récupérez pas un diff déjà stocké, et ne sondez pas les pipelines. Quelques appels ciblés sont acceptables, comme glab mr view lorsqu’un titre, une base ou un corps manque. Ne spammez pas glab, et ne commentez pas une merge request, ne l’approuvez pas et ne demandez pas de relecteurs.

Recherche de bugs

Lisez, dans l’ordre :

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 à côté de cette compétence

Appliquez la barrière, le passage spec et le passage standards du catalogue. Appliquez ensuite chaque section de langage qui correspond à un fichier dans les lignes ajoutées. Sautez les autres sections de langage.

Couvrez chaque chemin modifié dans la carte de bugs. Commencez par la section Lignes ajoutées (Added lines) . Cette section est le changement, un bloc par pull request. Un extrait de symbole peut être vide lorsque le diff a été récupéré à distance, et sur une pile, il ne représente que la pointe. Un extrait vide est un contexte manquant, pas un changement vide.

Ne vous arrêtez pas après le premier fichier probable. Pour chaque bloc source non-test dans les lignes ajoutées :

• Lisez tout le bloc, y compris les lignes en dessous lorsque le bloc indique que d’autres lignes se trouvent dans le fichier de preuves.
• Vérifiez ce bloc par rapport au catalogue, pas seulement la classe qui correspond au nom du fichier. Les cinq classes ci-dessous sont le minimum.
• Lorsqu’un fichier liste plus d’une pull request, révisez chaque bloc. Le corps cartographié n’est que la pointe de la pile.
• Ouvrez le fichier lorsque le bloc ne suffit pas à confirmer ou rejeter un bug.
• Pour chaque symbole modifié, inspectez les appelants et appelés à un saut que la carte liste lorsque le changement pourrait les casser.

Recherchez particulièrement une mauvaise branche, une valeur fausse ou vide traitée comme manquante, un décalage d’un ou un décalage de fuseau horaire, un verrou ou un statut qui bloque une nouvelle tentative après un échec, une URL ou une requête construite par concaténation, une vérification d’autorisation qui utilise la mauvaise identité, et un contrat que les appelants à un saut utilisent encore à l’ancienne. Un score d’impact élevé n’est pas une découverte et n’excuse pas de sauter un bloc.

Recherchez toutes ces classes :

• Logique et cas limites : mauvaises branches, décalage d’un, erreurs avalées, plantages null
• Perte de données et état : migrations, courses, écritures partielles, cache obsolète
• Contrats cassés : API, types, routes, comportement exporté, décalage de schéma
• Bugs de sécurité : lacunes d’autorisation, injections, secrets, limites de confiance non sûres
• Bugs de flux UX : impasses, états manquants (erreur, vide, chargement), navigation cassée

Recherchez des problèmes importants. Les pistes dans les paquets sont des indices, pas des découvertes. Une odeur de code, un fichier long, un test manquant ou une mise à jour de dépendance n’est une découverte que si la barrière du catalogue passe. Ignorez le formatage, les noms, les commentaires, les éloges, les questions et les refactorisations qui ne nomment pas un échec concret.

Écrire les découvertes

Écrivez .astroidal/findings.json :

{
  "findings": [
    {
      "pr": 12,
      "severity": "high",
      "description": "Ce qui casse, en une ou deux phrases.",
      "path": "src/auth.ts",
      "line": 12,
      "quote": "la ligne exacte copiée depuis le fichier",
      "recommendation": "Le changement spécifique qui supprime le bug.",
      "category": "security"
    }
  ]
}

severity est critical, high ou medium, en utilisant la barrière du catalogue. critical est un plantage, une perte de données, un contournement d’autorisation, une injection ou une exposition de secret sur un chemin que les utilisateurs empruntent. high est un résultat erroné réaliste, une écriture perdue, une course ou un contrat cassé. medium est un cas limite réaliste qui échoue. quote est une ligne exacte copiée d’un bloc de lignes ajoutées, du fichier cartographié ou de son voisin à un saut. Définissez pr sur la pull request qui a introduit cette ligne, ou omettez-le pour un changement local.

Dites ce qui casse, nommez le symbole et donnez le changement qui supprime le bug. Pour la sécurité et l’architecture, dites pourquoi ce changement tient. Ne tempérez pas, ne reformulez pas la ligne citée, ne posez pas de question. Un tableau findings vide n’est valide qu’après avoir vérifié les lignes ajoutées de chaque fichier source non-test par rapport au catalogue et qu’aucun d’eux ne contient un bug important.

Lorsque des fichiers modifiés appartiennent ensemble pour une raison que le répertoire ne montre pas déjà, nommez ce groupe. Le graphique dessine un répertoire tout seul, et il dessine une importation comme une ligne. Un groupe est pour un flux, une fonctionnalité ou un contrat partagé qui les traverse.

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

Utilisez un nom court et au moins deux chemins cartographiés. Omettez groups lorsque rien d’autre ne va ensemble.

Exécutez ensuite :

npx --yes astroidal rank

Si rank supprime une découverte parce que la citation ou le chemin est faux, corrigez cette découverte une fois et relancez rank. N’inventez pas un bug de remplacement pour garder le compte. Ne relancez pas rank une troisième fois.

Réponse

Écrivez un court résumé en prose dans le chat. Ouvrez avec une ligne que la personne peut copier-coller : Astroidal {score} · Réussi ou Astroidal {score} · Corrigez d’abord. Nommez ensuite les problèmes de plus haute sévérité et les deux chemins de sortie : .astroidal/review.md et .astroidal/constellation.html. Ne collez pas le tableau des découvertes. Ne recréez pas le graphique. L’humain décide toujours s’il faut fusionner.