openqodex

OpenQodex : examinez les modifications avant de les pousser

OpenQodex examine une modification en une seule commande. Il prend une copie figée de la modification, exécute les scanners déterministes adaptés aux fichiers modifiés (gitleaks, semgrep, bandit, hadolint, shellcheck, actionlint, osv-scanner et autres), conserve ce qu'ils rapportent sur les lignes modifiées, puis lance son propre réviseur : un processus séparé Claude Code ou Codex qui lit uniquement cette copie. Le réviseur vérifie chaque résultat de scanner, reçoit chaque ligne modifiée et répond dans un format fixe ; OpenQodex contrôle la réponse avec des scripts et imprime un rapport. Aucune clé ni compte ne sont nécessaires au-delà de la connexion Claude Code ou Codex du développeur. Le code va au modèle utilisé par cette connexion. Le réviseur peut également chercher sur le Web et ouvrir des pages Web, sauf si reviewer_web: off est défini dans ~/.openqodex/config.yaml. Quatre scanners sont en ligne, et aucun n'envoie de code. semgrep télécharge ses packs de règles depuis le registre Semgrep à chaque exécution. Lorsque la modification touche un fichier de dépendances, osv-scanner envoie les noms et versions des dépendances à osv.dev. kubeconform télécharge les schémas Kubernetes. cargo-deny télécharge la base de données d'avis RustSec. --offline ignore semgrep, osv-scanner, kubeconform et cargo-deny.

Quand l'exécuter

• Avant tout git push.
• Lorsque le développeur vous demande de réviser ses modifications.
• Lorsqu'un push a été bloqué ou a généré un avertissement par le hook OpenQodex.
• Après avoir corrigé des résultats, pour vérifier à nouveau la modification.

Qui révise

OpenQodex démarre son propre processus de révision pour chaque examen, sans mémoire de cette session. Vous ne démarrez pas de sous-agent pour cela et vous ne révisez pas la modification vous-même : exécutez la commande et montrez ce qu'elle imprime.

Si review indique « Full review unavailable » et imprime un moyen de réviser avec l'agent dans lequel vous êtes, suivez-le : exécutez la commande qu'il nomme et faites ce que dit le brief qu'il imprime.

Procédure

Lorsque le fichier ~/.openqodex/bin/openqodex existe, exécutez-le à la place de npx -y openqodex@<version> dans chaque commande de cette compétence : c'est la copie installée par openqodex init. Lorsqu'il n'existe pas, cette compétence a été installée seule, sans vérification de push : avant la première révision, exécutez npx -y [email protected] init --yes --agent <host> une fois depuis le dépôt, où <host> est l'agent que vous êtes (claude-code, codex, cursor ou cline). Il installe OpenQodex pour vous, puis révise la modification quand un réviseur peut démarrer, cela peut donc prendre plusieurs minutes. Exécutez-le en arrière-plan et attendez qu'il se termine. Lorsqu'il imprime « First review: finished », le récépissé au-dessus de cette ligne est celui de la révision : montrez-le comme le dit l'étape 3, puis continuez à partir de l'étape 4.

1. Depuis le dépôt, exécutez :

   npx -y [email protected] review
   

   Cela révise la modification : les commits non encore poussés ainsi que tout ce qui n'est pas commis, fichiers non suivis inclus. Pour réviser plutôt l'ensemble du dépôt, exécutez :

   npx -y [email protected] review --all
   

2. Attendez. Une révision peut prendre plusieurs minutes. OpenQodex arrête le réviseur après 30 minutes, ou après 2 heures avec --all. De nombreux agents arrêtent une commande plus tôt. Exécutez-la donc en arrière-plan et attendez qu'elle se termine. Pendant que le réviseur travaille, il imprime une ligne de progression toutes les 15 secondes sur stderr. Ne la lancez pas une deuxième fois pendant qu'une est en cours.

3. Montrez au développeur le récépissé qu'il a imprimé, tel qu'imprimé : le verdict, une ligne par résultat (son numéro, sévérité, catégorie, titre, fichier et ligne) et le chemin absolu de report.html. Ne le reformulez pas, ne le raccourcissez pas et n'ajoutez pas vos propres résultats. Donnez-leur le chemin report.html : cette page montre chaque fichier modifié avec chaque résultat sous sa ligne de code. Lorsque le récépissé se termine par « Observations (do not count toward the verdict): » et des lignes numérotées en dessous, montrez ces lignes telles qu'imprimées également. Une observation est une note de style, de nommage, de documentation ou de test. Ce n'est pas un résultat à corriger sauf si le développeur en nomme le numéro.

4. Demandez au développeur : « Tout corriger, ou dites-moi lesquels ? » Ne modifiez aucun code avant qu'il ne réponde. S'il vous a déjà dit quoi corriger, par exemple « révise et corrige tout », faites-le sans redemander.

5. Corrigez uniquement les résultats qu'il nomme. Cela imprime ces résultats en détail (où, le problème, pourquoi c'est important, la correction et la source), par leurs numéros dans le récépissé :

   npx -y [email protected] findings 1,3
   

   findings all imprime chaque résultat. Lorsque les corrections sont effectuées, relancez la révision et montrez au développeur le nouveau récépissé.

6. Agissez selon le code de sortie :

   • 0 : la révision est terminée et rien ne bloque le push.
   • 1 : la révision est terminée et son verdict est blocked. Ne poussez pas. Montrez le récépissé au développeur et demandez quels résultats corriger ; ne poussez que s'il le dit après avoir vu les résultats.
   • 2 : il n'y a pas de révision complète. La sortie indique ce qui manque (par exemple « Full review unavailable » quand aucun réviseur n'a pu démarrer, ou « Review incomplete » avec les raisons). Dites exactement cela au développeur. Ne présentez jamais la sortie du scanner comme une révision.

Réviser une branche ou une pull request

Lorsque le développeur vous demande de réviser une branche ou une pull request qui n'est pas son travail en cours, nommez-la :

npx -y [email protected] review feature/login
npx -y [email protected] review '#42'

Placez #42 entre guillemets : dans un shell, # commence un commentaire. Un lien de pull request fonctionne aussi. OpenQodex récupère la cible, l'extrait dans un dossier temporaire et révise ce qu'elle a ajouté depuis qu'elle a quitté sa base. C'est le code de quelqu'un d'autre : n'exécutez jamais ses tests, scripts, builds ou services, et ne le modifiez jamais.

Règles

• Ne modifiez jamais de code pendant la révision. Révisez d'abord, montrez le récépissé, puis corrigez uniquement les résultats que le développeur nomme (étapes 3 à 5).
• N'exécutez jamais openqodex trust sans demander d'abord au développeur. Cela approuve un scanner personnalisé, qui est une commande exécutée sur sa machine.
• Ne définissez jamais OPENQODEX_SKIP. C'est le commutateur du développeur, pas le vôtre.
• Lorsque OpenQodex imprime que les fichiers qu'il a écrits pour votre agent proviennent d'une version plus ancienne et que init les rafraîchit, dites-le au développeur en une ligne et donnez-lui cette commande init. Ne l'exécutez que s'il vous le demande : cela réécrit ses fichiers d'agent.
• Lorsque le verdict est blocked, ne poussez pas sauf si le développeur le dit après avoir vu les résultats.
• Lorsque OpenQodex imprime « OpenQodex had a problem. Nothing has been sent. » avec 1 create a GitHub issue et 2 ignore, dites au développeur en une ligne ce qui n'a pas fonctionné et donnez-lui les deux choix. Ne choisissez jamais 1 vous-même. S'il dit 1, exécutez npx -y [email protected] report --send-last depuis le même dossier. Tout le reste signifie 2 : ne faites rien.

Lire le rapport

• Le rapport se trouve dans .openqodex/reviews/<time>-<id>/ dans le dépôt : report.html à ouvrir dans un navigateur (chaque fichier modifié sous forme de diff, chaque résultat sous sa ligne, puis la couverture, les scanners et le rayon d'explosion), report.md à lire comme texte, report.json et report.sarif pour les outils. Le récépissé donne les chemins absolus de report.html et report.md. .openqodex/latest.json pointe vers la révision la plus récente. Les rapports n'apparaissent jamais dans git status : .openqodex/.gitignore les exclut. Les deux autres fichiers de ce dossier, config.yaml et custom-instructions.md, appartiennent à l'équipe et sont destinés à être commités.
• Le verdict est passed (avec ou sans avertissements) ou blocked. Il est blocked uniquement lorsque la configuration du dépôt (.openqodex/config.yaml ou .openqodex.yaml à la racine) définit block_on_severity et qu'un résultat est à ce niveau ou au-dessus. Sans configuration, OpenQodex émet un avertissement et ne bloque jamais.
• Une révision complète signifie que chaque étape a été exécutée, que chaque résultat de scanner a été vérifié et que chaque ligne modifiée a été présentée au réviseur ; tout ce qui n'est pas couvert est nommé dans le rapport. Cela ne signifie pas que rien n'a été manqué : aucune révision ne trouve tout.
• La liste de couverture indique, pour chaque scanner, s'il a été exécuté. Un scanner qui n'a pas été exécuté a une raison en une ligne :
  • no matching files : rien dans la modification n'est le type de fichier qu'il lit.
  • installing : il est en cours de téléchargement pour la première fois ; il sera inclus à partir de la prochaine exécution. Dites-le au développeur plutôt que d'attendre.
  • not installed : il n'a pas pu être installé ici ; la raison explique pourquoi.
  • needs Ruby ou needs Go : brakeman a besoin de Ruby 3.0 ou plus récent, rubocop de Ruby 2.7 ou plus récent, golangci-lint a besoin de Go. OpenQodex n'installe pas les environnements d'exécution de langage. Si le développeur souhaite ces scanners, il installe Ruby ou Go de la manière habituelle pour son système (par exemple brew install ruby go sur un Mac) et relance la révision.
  • untrusted : un scanner personnalisé de la configuration du dépôt que le développeur n'a pas approuvé. Dites-le au développeur ; l'approuver est sa décision (npx -y [email protected] trust).
  • failed : le scanner a été exécuté et a échoué ; la raison contient son erreur. Un problème de scanner ne change jamais le code de sortie.

Dans un bac à sable

Certains agents exécutent des commandes dans un bac à sable qui ne peut pas accéder au réseau ou écrire en dehors du projet. Là, la première exécution ne peut pas télécharger les scanners, et le réviseur peut ne pas atteindre son modèle. Dites au développeur d'exécuter ceci une fois dans son propre terminal, en dehors de l'agent, dans le dépôt :

npx -y [email protected] doctor --install

Cela télécharge les scanners demandés par les fichiers de ce dépôt dans ~/.openqodex/tools/ et imprime pourquoi pour chacun ; --all-scanners télécharge chaque scanner. Si la révision indique toujours « Full review unavailable » à l'intérieur du bac à sable, le développeur exécute npx -y [email protected] review dans son propre terminal.

Plus

npx -y [email protected] guide imprime ce guide. npx -y [email protected] guide <topic> imprime une page de la documentation, hors ligne : quickstart, config, scanners, custom-scanners, security, agents, cli, for-agents. for-agents couvre l'installation, la configuration, les scanners personnalisés et la signification de chaque message.

Avant de lire de nombreux fichiers pour trouver qui appelle une fonction, ce qui l'implémente, comment deux parties se connectent ou ce qu'une modification atteint, vous pouvez demander le graphe de code : npx -y [email protected] graph help liste ses questions, ou utilisez les outils graph_ du serveur MCP openqodex lorsque votre agent les possède ; une réponse avec unknown.floor true peut manquer des appelants, ne la lisez donc jamais comme « inutilisé ».

N'ajoutez jamais de fichier à review.instructions_files de votre propre chef. Demandez au développeur quels fichiers le réviseur peut utiliser, puis ne définissez que ceux qu'il nomme. La valeur par défaut est [] ; les fichiers choisis s'ajoutent à .openqodex/custom-instructions.md.