Référence de la ligne de commande

Synopsis

probe init [--repo PATH] [--language go|typescript|javascript|python|rust]
probe lint [--base main] [--head HEAD] [--ci] [flags]
probe review [--base main] [--reviewer=false] [--ci] [flags]
probe review [flags] BASE..HEAD
probe plan --intent-file FILE [--base main] [--ci]
probe review --plan .probe/PLAN.json [flags]
probe report [--input .probe/confidence-report.json] [--out DIR] [--format LIST] [--report-url URL]
probe version

• lint analyse une modification de façon statique. Il n’exécute jamais le code du dépôt et n’appelle jamais de fournisseur d’IA.
• review ajoute des vérifications en bac à sable dans Docker, les étapes de preuve optionnelles (tests de référence modifiés, tests impactés, fuzzing différentiel, mutation, préparation des dépendances) et, lorsqu’un modèle est configuré, une investigation par IA.
• plan demande au fournisseur configuré un plan d’implémentation avant l’écriture du moindre code, l’évalue avec des règles fixes et le transforme en un contrat auquel lint --plan et review --plan comparent le diff.
• Seuls les fichiers commités sont analysés ; les modifications non commitées et les fichiers non suivis sont ignorés.
• Par défaut, les rapports sont écrits dans .probe/ dans le dépôt. La sortie console reste concise.
• Les options acceptent un ou deux tirets (-ci ou --ci). Les booléens s’activent avec --ci ou --ci=true et se désactivent avec --checks=false. Une valeur s’écrit --base main ou --base=main.
• Lancez probe <command> --help pour afficher les options d’une commande.

Choisir les révisions

Les deux côtés d’une comparaison sont résolus en identifiants de commit immuables, enregistrés dans le rapport. Les renommages, suppressions, fichiers binaires et changements de type de fichier sont pris en charge.

Une plage peut figurer avant ou après les options : probe review main..HEAD --ci et probe review --ci main..HEAD sont équivalents. Une seule plage est acceptée au maximum. Toute révision comprise par Git fonctionne : branches, tags, origin/main, HEAD~3 ou un identifiant de commit. Les jobs de CI ont besoin d’un historique suffisant pour résoudre la base (par exemple fetch-depth: 0).

La politique de confiance est toujours lue depuis la branche de base, jamais depuis la modification relue : une pull request ne peut donc pas assouplir ses propres règles.

probe lint

Analyse statique d’une modification : comparaison Git, signaux de risque et rapport. Pas de Docker, pas d’appel à un fournisseur, aucune exécution du code du dépôt. Sans danger sur des branches non fiables.

probe lint HEAD~1..HEAD                 # the last commit
probe lint --base origin/main --ci      # this branch as a pull request, for CI
probe lint --base main --format json    # JSON report only
probe lint --base main --plan .probe/PLAN.json   # scope drift against an approved plan

probe review

Tout ce que fait lint, plus les commandes test, typecheck, build et coverage de la politique dans des conteneurs Docker jetables, plus une investigation par IA lorsqu’un modèle est configuré. Nécessite Docker avec des conteneurs Linux et une sandbox.image préchargée.

probe review --base main --ci                        # typical pull request run
probe review HEAD~1..HEAD --reviewer=false           # checks only, no provider
probe review --base main --checks=false --reviewer=false   # static only, like lint
probe review --base main --intent-file PR.md         # give acceptance criteria
probe review --base main --impacted-tests --base-tests --ci   # run tests on both revisions
probe review --base main --format markdown,json,sarif,pr-comment --report-url "$RUN_URL"

La préparation des dépendances s’exécute en premier, lorsque la politique contient un objet prepare. Les vérifications s’exécutent ensuite dans l’ordre test, typecheck, build, puis coverage, suivies des étapes de preuve et du relecteur. Chaque conteneur tourne sans root, avec une racine et un montage des sources en lecture seule, sans capacité ajoutée, sans réseau par défaut, et avec les limites de CPU, de mémoire, de PID et de durée de la politique du bac à sable. Le socket Docker, votre copie de travail et les clés d’API ne sont jamais montés. Si Docker ou l’image est absent, l’exécution se termine avec le code 4 ; rien ne bascule jamais sur votre machine hôte.

probe plan

Avant l’écriture de la modification : le fournisseur configuré simule, en lecture seule, la façon dont il implémenterait une intention au commit de base et soumet un plan structuré (fichiers, symboles, dépendances, étapes). Probe l’évalue avec des règles fixes et écrit PLAN.json et PLAN.md. Le modèle produit le plan ; il n’en juge jamais le risque. Rien n’est modifié ni exécuté.

Les outils du planificateur sont en lecture seule et travaillent sur un instantané du commit de base : list_files, read_file, search_code et, adossés à l’index, find_references, inspect_symbol et find_callers, puis submit_plan une seule fois. L’évaluation signale quatre catégories à partir du plan et du commit de base uniquement :

Codes de sortie : 0 ; 2 avec --ci lorsqu’une catégorie est signalée ; 3 utilisation ou configuration ; 4 échec du fournisseur ou aucun plan accepté.

Dérive du périmètre : --plan

lint --plan et review --plan lisent le contrat du plan et le comparent au diff réel. Chaque écart dans le diff devient aussi un signal plan_drift. La section est drifted lorsqu’un élément est de niveau moyen ou supérieur.

probe plan --intent-file task.md --ci                     # 1. plan; exit 2: a human validates it
# 2. an agent implements the plan
probe review --base origin/main --plan .probe/PLAN.json --ci   # 3-4. exit 0: merge; exit 2: review

La plan gate

review --plan se termine par une décision, plan_drift.decision, affichée sur stdout et en tête de la section Plan Conformance. Avec --ci, c’est le code de sortie.

Les options et le contrat stockés dans PLAN.json ne sont jamais considérés comme fiables : le contrat est redérivé de la proposition, si bien qu’un plan modifié ne peut pas élargir le périmètre sans évaluation, et probe report recalcule la décision à partir du rapport enregistré. La gate est une décision de processus, pas un verdict sur la correction. Un plan qui ne signale rien ne prouve pas que la modification est sûre, et la dérive ne vérifie pas que la modification met en œuvre l’intention. Voir les plans préalables et la recette CI.

probe init

Écrit un .probe.json de départ pour le projet. Refuse d’écraser un fichier existant. Relisez les commandes et l’image, puis commitez le fichier sur votre branche de base.

probe report

Régénère le rendu d’un rapport JSON enregistré, par exemple pour recréer le Markdown ou produire du SARIF en CI. Rien n’est réexécuté, et le nouveau rendu n’authentifie pas les preuves qu’il contient ; chaque statut est redérivé des vérifications enregistrées, si bien qu’un rapport modifié est corrigé plutôt que cru sur parole.

probe version et aide

Codes de sortie

Aucun code ne signifie « approuvé ». Un 0 indique que rien n’a été reproduit, pas que la modification est correcte.

Variables d’environnement

Le fournisseur d’IA relève du déploiement plutôt que du dépôt : ces réglages peuvent donc venir de l’environnement. Rien d’autre ne le peut : l’image, les commandes, les budgets et les chemins sensibles sont toujours décidés par la politique de confiance.

Une variable vide est considérée comme non définie. Les fichiers de clé sont lus en entier, espaces de début et de fin retirés, limités à 8 Kio, et doivent tenir sur une seule ligne. Lorsque le relecteur s’exécute, le journal indique la provenance de chaque valeur, jamais la valeur elle-même. Quiconque contrôle cet environnement choisit où le code source expurgé est envoyé : tenez-le à l’écart des jobs qui exécutent du code de forks non fiables.

Fichiers produits

Ajoutez .probe/ à .gitignore. La console affiche un seul résumé : fichiers et lignes modifiés, nombre de signaux et de problèmes reproduits, surface de relecture ciblée et exécution des lignes modifiées.

Signaux de risque

Les signaux sont des raisons de regarder, pas des défauts confirmés. Les fichiers Go bénéficient d’une analyse syntaxique ; TypeScript/JavaScript, Python, Rust et les autres langages utilisent des heuristiques textuelles étiquetées comme telles. Les signaux portant sur les mêmes lignes sont fusionnés en une seule plage de relecture dans le rapport. Les signaux au niveau du fichier (sensitive_path, dependency_change, migration_change, infrastructure_change, binary_change, file_deleted, file_type_change, large_change, branch_growth, no_test_change, prepare_input_changed, plan_drift) concernent le fichier, pas une ligne : le rapport les liste sous le fichier avec la mention fichier entier, et le JSON les marque "scope": "file". Leur line ne sert qu’à les placer sur la première ligne modifiée du fichier.

Analyse d’impact

Avec --impact (par défaut), lint et review construisent sur l’hôte un index statique du commit candidat, à partir des objets Git commités, sans exécuter le code du dépôt. Pour chaque fonction modifiée, il liste les endroits du code inchangé qui l’appellent et les tests existants qui l’atteignent en 3 appels au plus, ajoute des signaux impacted_caller faibles et alimente les outils find_references, inspect_symbol et find_callers du relecteur.

Chaque réponse est approximative : un appelant listé est un endroit à relire, et l’absence d’appelant ne prouve pas qu’il n’en existe aucun. --impacted-tests n’exécute que les tests Go qui atteignent la fonction. Voir l’analyse d’impact.

Langages

Fichier de politique : .probe.json

La politique décide quelles commandes s’exécutent, dans quelle image, avec quelles limites, et si un fournisseur d’IA est utilisé. Elle est lue depuis .probe.json sur la branche de base, ou depuis --config PATH. En son absence, les valeurs par défaut intégrées pour le langage détecté s’appliquent. Les clés omises prennent les valeurs par défaut indiquées ci-dessous.

Le fichier doit être un unique objet JSON de 1 Mio au maximum. Les clés inconnues, les noms de commande inconnus et les clés en double sont rejetés avec le code 3 : un binaire plus ancien rejette donc une clé qu’il ne connaît pas.

{
  "version": 1,
  "language": "go",
  "commands": {
    "test": ["go", "test", "./..."],
    "typecheck": ["go", "vet", "./..."],
    "build": ["go", "build", "./..."],
    "generated_test": ["go", "test", "{package}"],
    "coverage": ["go", "test", "-covermode=count", "-coverprofile={coverage_out}", "./..."]
  },
  "sandbox": { "image": "golang:1.26-bookworm", "network": false, "timeout_seconds": 120,
               "max_runtime_seconds": 600, "max_output_bytes": 65536, "memory_mb": 1024, "cpus": 2 },
  "reviewer": { "endpoint": "https://api.openai.com/v1/chat/completions", "model": "",
                "api_key_env": "PROBE_API_KEY", "max_iterations": 20, "max_generated_tests": 10,
                "timeout_seconds": 600, "max_input_bytes": 131072 },
  "sensitive_paths": ["**/auth/**", "**/payment*/**", "**/migrations/**", ".github/workflows/**", ".probe.json"]
}

commands

Chaque commande est un tableau argv, pas une chaîne shell : ["npm", "test"], jamais "npm test". 128 arguments au maximum ; ne configurez que les vérifications que votre projet fournit.

sandbox

reviewer

sensitive_paths

Motifs glob de chemins qui lèvent toujours un signal sensitive_path élevé lorsqu’ils sont modifiés. Les chemins sont relatifs à la racine du dépôt, avec des barres obliques ; * correspond au sein d’un segment de chemin et ** à travers les segments. Les chemins absolus, les barres obliques inverses et .. sont rejetés.

fuzz v0.4

Fait passer les mêmes entrées à graine fixe dans chaque fonction Go de niveau package modifiée et chaque fonction TS/JS exportée modifiée (à signature inchangée), sur la base et sur le candidat, puis compare ce que les deux révisions ont enregistré. Une fonction diverged est une observation, jamais un défaut : elle demande une relecture (code 2 avec --ci) et ne produit jamais le code 1. {} l’active avec les valeurs par défaut.

mutation v0.4

Apporte de petites modifications déterministes aux lignes ajoutées des fichiers Go modifiés hors tests et exécute les tests du package une fois par mutant. Un mutant qu’aucun test ne remarque devient un signal surviving_mutant moyen ; aucun score n’est calculé. Les quatre clés sont obligatoires.

"mutation": {
  "command": ["go", "test", "-json", "-count=1", "-failfast", "{package}"],
  "max_mutants": 20, "timeout_seconds": 60, "max_runtime_seconds": 300
}

prepare v0.4

Permet à la politique de confiance de la branche de base de construire la couche de dépendances : avant l’exécution de tout code candidat, sa commande s’exécute une fois, dans un conteneur borné, sur les fichiers de dépendances exportés depuis le commit de base, et le conteneur devient l’image locale de toutes les vérifications. Une review ultérieure avec la même base et les mêmes entrées la réutilise. Si aucune image n’est produite, la review sort avec le code 4 ; elle ne se rabat jamais sur l’image non préparée.

"prepare": { "command": ["go", "mod", "download"], "inputs": ["go.mod", "go.sum"], "network": true }

Valeurs par défaut par langage

Écrites par probe init et utilisées lorsque la branche de base n’a pas de politique. Les images standard Node.js, Python et Rust ne contiennent pas vos dépendances : construisez une image qui les contient, ou ajoutez un objet prepare, et adaptez les commandes.

Relecteur IA

Facultatif. Lorsqu’un modèle est configuré, review le laisse examiner la modification avec des outils bornés : lecture de fichiers et de diffs expurgés, recherche dans le code source, consultation des références et des appelants dans l’index statique, exécution des vérifications existantes, création et exécution de tests temporaires sur la base et sur le candidat. Il n’a ni shell ni accès aux URL. Ses affirmations restent des hypothèses tant qu’un test ne reproduit pas une différence.

{
  "reviewer": {
    "endpoint": "https://your-provider.example/v1",
    "model": "your-tool-capable-model",
    "api_key_env": "PROBE_API_KEY"
  }
}

export PROBE_API_KEY=…                       # from your shell or CI secret store
probe review --base main --config .probe.json   # try it before committing
probe review --base main --reviewer=false            # turn it off for one run

• Seuls la politique de confiance, --config ou l’environnement de déploiement peuvent activer le relecteur ; une pull request ne le peut pas.
• Un contexte source borné et expurgé est envoyé au fournisseur. Le masquage des secrets se fait au mieux ; utilisez un fournisseur local (par exemple http://127.0.0.1:1234/v1) si le code source doit rester en local.
• Les clés d’API n’entrent jamais dans les conteneurs de test. lint n’appelle jamais de fournisseur.
• En cas de défaillance du fournisseur ou d’épuisement des budgets, les résultats déterministes sont conservés et l’investigation est marquée incomplète ; avec --ci, cela exige une relecture humaine.