Riferimento della riga di comando

Sintassi

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 analizza una modifica staticamente. Non esegue mai il codice del repository e non chiama mai un provider di IA.
• review aggiunge controlli in sandbox su Docker, le fasi di evidenza facoltative (test della baseline modificati, test impattati, fuzzing differenziale, mutation testing, preparazione delle dipendenze) e, quando è configurato un modello, un'indagine dell'IA.
• plan chiede al provider configurato un piano di implementazione prima che venga scritto codice, lo valuta con regole fisse e lo trasforma in un contratto rispetto al quale lint --plan e review --plan verificano il diff.
• Vengono analizzati solo i file committati; le modifiche non committate e i file non tracciati vengono ignorati.
• Per impostazione predefinita i report vengono scritti in .probe/ nel repository. L'output della console resta breve.
• I flag accettano uno o due trattini (-ci o --ci). I booleani si attivano con --ci o --ci=true e si disattivano con --checks=false. Un valore si passa come --base main o --base=main.
• Esegui probe <command> --help per vedere i flag di un comando.

Scelta delle revisioni

Entrambi i lati di un confronto vengono risolti in ID di commit immutabili, registrati nel report. Rinomine, eliminazioni, file binari e cambi di tipo di file sono gestiti.

Un intervallo può comparire prima o dopo i flag: probe review main..HEAD --ci e probe review --ci main..HEAD sono equivalenti. È accettato al massimo un intervallo. Funziona qualsiasi revisione che Git comprende: branch, tag, origin/main, HEAD~3 o un ID di commit. I job di CI hanno bisogno di una cronologia sufficiente per risolvere la base (per esempio fetch-depth: 0).

La policy attendibile viene sempre letta dal branch di base, mai dalla modifica in revisione, così una pull request non può allentare le proprie regole.

probe lint

Analisi statica di una modifica: confronto Git, segnali di rischio e un report. Niente Docker, nessuna chiamata a provider, nessuna esecuzione del codice del repository. Sicuro da eseguire su branch non attendibili.

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

Tutto ciò che fa lint, più i comandi test, typecheck, build e coverage della policy in container Docker usa e getta, più un'indagine dell'IA quando è configurato un modello. Richiede Docker con container Linux e una sandbox.image precaricata.

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 preparazione delle dipendenze viene eseguita per prima, quando la policy ha un oggetto prepare. Poi i controlli vengono eseguiti nell'ordine test, typecheck, build, quindi coverage, seguiti dalle fasi di evidenza e dal revisore. Ogni container è non-root, ha una root e un mount del codice sorgente in sola lettura, nessuna capability aggiuntiva, nessuna rete per impostazione predefinita e i limiti di CPU, memoria, PID e tempo della policy della sandbox. Il socket Docker, il tuo checkout di lavoro e le chiavi API non vengono mai montati. Se Docker o l'immagine mancano, l'esecuzione termina con uscita 4; non si ripiega mai sul tuo host.

probe plan

Prima che la modifica venga scritta: il provider configurato simula, in sola lettura, come implementerebbe un intento al commit di base e presenta un piano strutturato (file, simboli, dipendenze, passaggi). Probe lo valuta con regole fisse e scrive PLAN.json e PLAN.md. Il modello produce il piano; non ne giudica mai il rischio. Nulla viene modificato o eseguito.

Gli strumenti del pianificatore sono in sola lettura e lavorano su uno snapshot del commit di base: list_files, read_file, search_code e, basati sull'indice, find_references, inspect_symbol e find_callers, poi submit_plan una sola volta. La valutazione segnala quattro categorie basandosi solo sul piano e sul commit di base:

Codici di uscita: 0; 2 con --ci quando una categoria viene segnalata; 3 uso o configurazione; 4 errore del provider o nessun piano accettato.

Deriva dall'ambito: --plan

lint --plan e review --plan leggono il contratto del piano e lo confrontano con il diff reale. Ogni differenza nel diff diventa anche un segnale plan_drift. La sezione è drifted quando una voce è di livello medio o superiore.

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

Il plan gate

review --plan si conclude con una decisione, plan_drift.decision, stampata su stdout e in cima alla sezione Plan Conformance. Con --ci, è il codice di uscita.

I flag e il contratto memorizzati in PLAN.json non sono mai considerati attendibili: il contratto viene ricavato di nuovo dalla proposta, così un piano modificato non può ampliare l'ambito senza essere valutato, e probe report ricalcola la decisione dal report registrato. Il gate è una decisione di processo, non un verdetto di correttezza. Un piano che non segnala nulla non prova che la modifica sia sicura, e la verifica della deriva non controlla che la modifica implementi l'intento. Vedi i piani preliminari alla modifica e la ricetta per la CI.

probe init

Scrive un .probe.json iniziale per il progetto. Si rifiuta di sovrascrivere un file esistente. Rivedi i comandi e l'immagine, poi committa il file sul tuo branch di base.

probe report

Rigenera un report JSON salvato, per esempio per riprodurre il Markdown o produrre SARIF in CI. Nulla viene rieseguito, e la rigenerazione non autentica le prove che contiene; ogni stato viene ricavato di nuovo dai controlli registrati, così un report modificato viene corretto anziché considerato attendibile.

probe version e aiuto

Codici di uscita

Nessun codice significa "approvato". Uno 0 dice che non è stato riprodotto nulla, non che la modifica è corretta.

Variabili d'ambiente

Il provider di IA appartiene al deployment e non al repository, quindi queste impostazioni possono provenire dall'ambiente. Nient'altro può: immagine, comandi, budget e percorsi sensibili sono sempre decisi dalla policy attendibile.

Una variabile vuota conta come non impostata. I file delle chiavi vengono letti per intero eliminando gli spazi iniziali e finali, sono limitati a 8 KiB e devono contenere una sola riga. Quando il revisore viene eseguito, il log indica da dove proviene ogni valore, mai il valore stesso. Chi controlla questo ambiente sceglie dove viene inviato il codice sorgente oscurato: tienilo fuori dai job che eseguono codice non attendibile proveniente da fork.

File di output

Aggiungi .probe/ a .gitignore. La console stampa un unico riepilogo: file e righe modificati, numero di segnali e di problemi riprodotti, la superficie di revisione mirata e l'esecuzione delle righe modificate.

Segnali di rischio

I segnali sono motivi per guardare, non difetti confermati. I file Go ricevono un'analisi basata sulla sintassi; TypeScript/JavaScript, Python, Rust e gli altri linguaggi usano euristiche testuali etichettate. I segnali sulle stesse righe vengono uniti in un unico intervallo di revisione nel report. I segnali a livello di file (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) riguardano il file, non una riga: il report li elenca sotto il file come intero file, e il JSON li contrassegna con "scope": "file". La loro line serve solo a collocarli sulla prima riga modificata del file.

Analisi d'impatto

Con --impact (il predefinito), lint e review costruiscono sull'host un indice statico del commit candidato, a partire dagli oggetti Git committati, senza eseguire codice del repository. Per ogni funzione modificata elenca i punti del codice non modificato che la chiamano e i test esistenti che la raggiungono entro 3 chiamate, aggiunge segnali impacted_caller di livello basso e alimenta gli strumenti find_references, inspect_symbol e find_callers del revisore.

Ogni risposta è approssimativa: un chiamante elencato è un punto da rivedere, e l'assenza di un chiamante non prova che non ne esistano. --impacted-tests esegue solo i test Go che raggiungono la funzione. Vedi analisi d'impatto.

Linguaggi

File di policy: .probe.json

La policy decide quali comandi vengono eseguiti, in quale immagine, con quali limiti, e se viene usato un provider di IA. Viene letta da .probe.json sul branch di base, oppure da --config PATH. In sua assenza si applicano i valori predefiniti integrati per il linguaggio rilevato. Le chiavi che ometti assumono i valori predefiniti indicati qui sotto.

Il file deve essere un unico oggetto JSON di al massimo 1 MiB. Chiavi sconosciute, nomi di comando sconosciuti e chiavi duplicate vengono rifiutati con uscita 3, così un binario più vecchio rifiuta una chiave che non conosce.

{
  "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

Ogni comando è un array argv, non una stringa di shell: ["npm", "test"], mai "npm test". Al massimo 128 argomenti; configura solo i controlli che il tuo progetto prevede.

sandbox

reviewer

sensitive_paths

Glob di percorsi che sollevano sempre un segnale sensitive_path alto quando vengono modificati. I percorsi sono relativi alla radice del repository, con barre in avanti; * corrisponde all'interno di un segmento di percorso e ** attraverso i segmenti. Percorsi assoluti, backslash e .. vengono rifiutati.

fuzz v0.4

Esegue gli stessi input generati da un seed su ogni funzione Go a livello di package modificata e su ogni funzione TS/JS esportata modificata (con firma invariata), sulla baseline e sulla candidata, e confronta ciò che le due revisioni hanno registrato. Una funzione diverged è un'osservazione, mai un difetto: richiede una revisione (uscita 2 con --ci) e non produce mai l'uscita 1. {} la attiva con i valori predefiniti.

mutation v0.4

Apporta piccole modifiche deterministiche alle righe aggiunte dei file Go modificati che non sono di test ed esegue i test del package una volta per mutante. Un mutante che nessun test rileva diventa un segnale surviving_mutant medio; non viene calcolato alcun punteggio. Tutte e quattro le chiavi sono obbligatorie.

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

prepare v0.4

Consente alla policy attendibile del branch di base di costruire il livello delle dipendenze: prima che venga eseguito qualsiasi codice candidato, il suo comando viene eseguito una volta, in un container con limiti, sui file delle dipendenze esportati dal commit di base, e il container diventa l'immagine locale di ogni controllo. Una review successiva con la stessa base e gli stessi input la riutilizza. Se non produce alcuna immagine, la review termina con uscita 4; non ripiega mai sull'immagine non preparata.

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

Valori predefiniti per linguaggio

Scritti da probe init e usati quando il branch di base non ha una policy. Le immagini standard di Node.js, Python e Rust non contengono le tue dipendenze: costruisci un'immagine che le contenga, oppure aggiungi un oggetto prepare, e adatta i comandi.

Revisore IA

Facoltativo. Quando è configurato un modello, review gli permette di indagare sulla modifica con strumenti limitati: leggere file e diff oscurati, cercare nel codice sorgente, consultare riferimenti e chiamanti nell'indice statico, eseguire i controlli esistenti, e creare ed eseguire test temporanei sulla base e sulla candidata. Non ha shell né strumenti per scaricare URL. Le sue affermazioni restano ipotesi finché un test non riproduce una differenza.

{
  "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

• Solo la policy attendibile, --config o l'ambiente di deployment possono attivare il revisore; una pull request non può.
• Al provider viene inviato un contesto di codice sorgente limitato e oscurato. Il mascheramento dei segreti è best effort; usa un provider locale (per esempio http://127.0.0.1:1234/v1) se il codice sorgente deve restare in locale.
• Le chiavi API non entrano mai nei container di test. lint non chiama mai un provider.
• Gli errori del provider e i budget esauriti conservano i risultati deterministici e segnano l'indagine come incompleta; con --ci questo richiede una revisione umana.