--base/--target (e ogni altra opzione) si applicano allo stesso modo a ogni repository della lista, quindi la modalità multi-repo funziona meglio quando tutti fanno diff rispetto alla stessa cosa (es. il main di tutti). Repository con convenzioni diverse richiedono esecuzioni separate.

Flag

Cosa analizzare

• --base, -b (nessuno): ref da cui fare il diff, es. main o HEAD~3. Se omesso, zairo analizza le modifiche non committate.
• --target, -t (nessuno): ref verso cui fare il diff. Richiede --base; se omesso (con --base impostato), fa il diff rispetto alla tua working tree.
• --depth, -d (1): quanti salti di chiamanti/chiamati includere nel grafo d'impatto attorno a ogni modifica.
• --language, -l (auto): forza un linguaggio invece di lasciare che Trailmark lo rilevi automaticamente.

Analisi LLM

• --graph-only (disattivato): salta l'analisi delle vulnerabilità e costruisce solo il grafo d'impatto — nessun finding, nessun report.sarif.
• --model (gemini/gemini-2.5-pro): qualsiasi stringa di modello LiteLLM.
• --concurrency, -c (5): richieste LLM parallele, all'interno dell'analisi di un singolo repository.
• --batch-size (1): raggruppa questo numero di nodi in un'unica richiesta LLM invece di una chiamata per nodo — meno richieste (aiuta con i limiti di rate del provider), al costo di un isolamento dei guasti condiviso: una risposta errata/malformata fa fallire ogni nodo di quel batch, non solo uno. La cache resta comunque per singolo nodo.
• --max-tokens (4096): budget di output per richiesta. I modelli di reasoning consumano questo budget anche per il pensiero interno, quindi aumentalo se vedi risposte vuote.
• --cache / --no-cache (cache attiva): salta la ri-analisi del codice invariato dall'ultima esecuzione (memorizzato tramite hash del contenuto in <output>/.llm_cache.json).
• --tokens (disattivato): stampa quanti token l'analisi ha effettivamente usato (i cache hit non contano, poiché non hanno effettuato chiamate).

Output e gating

• --output, -o (zairo_out): dove finiscono i report. Modalità multi-repo: ogni repository riceve la propria cartella <output>/<repo-slug>/, più un rollup.* combinato qui.
• --fail-on (nessuno): esce con codice non-zero se emerge un finding a questa gravità o superiore (low/medium/high/critical). Errore se combinato con --graph-only (non ci sarebbe nulla su cui fare gating). Modalità multi-repo: verificato su tutti i repository combinati. Vedi Gating CI / PR.
• --verbose, -v (disattivato): stampa cosa succede passo dopo passo (comandi git, setup della worktree, avanzamento dell'analisi per nodo).
• --debug, -vv (disattivato): tutto ciò che stampa --verbose, più il prompt esatto inviato all'LLM e la sua risposta grezza per ogni nodo — scritto in <output>/debug.log (per repository in modalità multi-repo), poiché è troppo per stamparlo in console.

Solo modalità multi-repo

• --repos-file (nessuno): un percorso di repository per riga (commenti # consentiti), unito a qualsiasi repository passato direttamente.
• --repo-concurrency (1): quanti repository analizzare contemporaneamente. Le richieste LLM totali in volo possono raggiungere --concurrency × --repo-concurrency, quindi tieni d'occhio i limiti di rate del tuo provider. Sopra 1, l'avanzamento stampa una riga di riepilogo per repository al completamento invece del dettaglio passo-passo in tempo reale.
• --continue-on-error / --stop-on-error (continua): continua ad analizzare il resto della lista, o fermati, quando un repository fallisce. In ogni caso, qualsiasi repository fallito fa comunque fallire il codice di uscita complessivo.

Esegui zairo --help in qualsiasi momento per vedere questa stessa lista dalla CLI.

File di output

• report.json (sempre): il grafo d'impatto grezzo (nodi, archi e qualsiasi finding allegato), come dati.
• report.html (sempre): un visualizzatore di grafi di dipendenze interattivo e autonomo (Cytoscape.js). Clicca un nodo per vedere i suoi finding.
• report.sarif (a meno che non si usi --graph-only): finding in formato SARIF 2.1.0, per GitHub code scanning o qualsiasi altro consumatore SARIF. Viene sempre scritto, anche per un'analisi pulita (un log vuoto ma valido), così un'interfaccia di scanning può segnare come risolti gli alert precedentemente segnalati. I finding sono raggruppati in regole per CWE quando il modello ne ha taggata una, così i problemi ricorrenti dello stesso tipo si compattano in un'unica regola invece di una nuova per ogni variante di formulazione.

La modalità multi-repo produce gli stessi tre file per repository, più rollup.json / rollup.html / rollup.sarif: stato e conteggi di gravità per repository, una tabella dashboard che collega ai report di ogni repository, e i risultati SARIF di ogni repository uniti in un unico log multi-run.

Codice eliminato

Una funzione/classe/modulo rimosso completamente (non solo modificato) appare comunque in report.html, con stato deleted: un nodo tratteggiato e attenuato che segna dove si trovava. Il grafo di Trailmark non può rappresentarlo da solo (riflette solo l'albero così com'è ora), quindi zairo rileva le eliminazioni separatamente: analizza anche i file modificati come esistevano in --base (o HEAD, se --base non è stato fornito) e confronta i due insiemi di simboli. Una funzione eliminata non viene mai inviata allo scanner LLM (non resta codice vivo da analizzare), quindi porta solo il suo nome, tipo e posizione precedente, mai finding.

Gating CI / PR

--fail-on <low|medium|high|critical> esce con codice non-zero se viene trovato un finding a quella gravità o superiore (su tutti i repository combinati, in modalità multi-repo), così uno step CI può bloccare un merge su questa base. Un paio di cose da sapere:

• Dà errore se combinato con --graph-only (non ci sarebbe nulla su cui fare gating).
• Non sopprime mai l'output SARIF: viene comunque scritto anche quando il gate fallisce, così un'interfaccia di scanning riflette lo stato corrente in ogni caso.

Vedi examples/github-actions/zairo-pr-scan.yml per un workflow completo di scansione PR: esegue zairo sul diff della PR, carica report.sarif nel code scanning di GitHub e fa fallire il job se il gate fallisce.