Comandi CLI
Riferimento completo per ogni comando, flag e codice di uscita Zenzic.
Controlli
# Controlli individuali
zenzic check links # Link interni; aggiungi --strict per la validazione HTTP esterna
zenzic check orphans # Pagine su disco mancanti dalla nav
zenzic check snippets # Blocchi Python che non compilano
zenzic check placeholders # Pagine stub: basso conteggio parole o pattern vietati
zenzic check assets # File media non referenziati da nessuna pagina
zenzic check references # Reference-style link + Zenzic Shield (rilevamento credenziali)
# Tutti i controlli in sequenza
zenzic check all # Esegue tutti i controlli
zenzic check all --strict # Valida anche gli URL esterni; tratta i warning come errori
zenzic check all --format json # Output machine-readable
zenzic check all --exit-zero # Segnala problemi ma esce sempre con codice 0
zenzic check all --quiet # Output minimale a riga singola per pre-commit e CI
zenzic check all --engine mkdocs # Sovrascrive il motore rilevato
zenzic check links --show-info # Mostra finding di livello info (es. link circolari)
Flag globali
Questi flag controllano il profilo signal-to-noise di Zenzic tra scansioni quotidiane, gate CI e risposta agli incidenti.
--strict
| Comando | Effetto |
|---|---|
check links --strict | Valida gli URL HTTP/HTTPS esterni via richieste di rete concorrenti |
check all --strict | Valida gli URL esterni + tratta i warning come errori |
check references --strict | Tratta le Dead Definitions (reference link non usati) come errori bloccanti |
score --strict / diff --strict | Esegue il link check in modalità strict |
Puoi anche impostare strict = true in zenzic.toml per renderlo il default permanente.
--exit-zero
Esce sempre con codice 0 anche quando vengono trovati problemi. Tutti i problemi vengono
comunque stampati e inclusi nel punteggio — solo il codice di uscita viene soppresso. Utile per
pipeline di sola osservazione.
Gli eventi di sicurezza non vengono mai declassati da questo flag: Exit 2 (violazione Shield) ed Exit 3 (incidente Blood Sentinel su path di sistema) mantengono sempre priorità sui fallimenti ordinari.
Puoi anche impostare exit_zero = true in zenzic.toml per renderlo il default permanente.
--show-info
Per impostazione predefinita, i finding di livello info sono nascosti per mantenere l'output
quotidiano concentrato sulle violazioni azionabili. Usa --show-info quando vuoi piena visibilità
Sentinel sui segnali non bloccanti, come la topologia dei cicli link (CIRCULAR_LINK).
Disponibile su tutti i comandi zenzic check.
zenzic check links --show-info
zenzic check all --show-info
--quiet
--quiet è disponibile su zenzic check all ed è pensato per i Silent Builders
(pre-commit e hook CI) che richiedono output minimo.
- Sopprime il pannello Sentinel ricco e il report verboso per file.
- Stampa una sintesi compatta a riga singola per errori/warning.
- Stampa una riga di sicurezza esplicita per violazioni Shield (Exit 2).
- Mantiene comunque l'enforcement degli exit code fatali, inclusa la priorità sicurezza (
3 > 2 > 1).
zenzic check all --quiet
Inizializzazione
zenzic init # Crea zenzic.toml nel progetto corrente
zenzic init --pyproject # Scrive la config in pyproject.toml [tool.zenzic]
zenzic init --force # Sovrascrive la config esistente senza prompt
zenzic init --plugin plugin-scaffold-demo # Crea un pacchetto SDK plugin
Rilevamento intelligente — quando pyproject.toml esiste nella root del progetto,
zenzic init chiede se incorporare la configurazione lì come tabella [tool.zenzic]
invece di creare un file zenzic.toml separato. Usa --pyproject per saltare il
prompt e scrivere direttamente in pyproject.toml.
Il rilevamento automatico dell'engine è incluso in entrambe le modalità: se mkdocs.yml
o zensical.toml è presente, la configurazione generata preimposta il campo engine.
Se non viene trovato alcun file di configurazione engine, si applicano i default
vanilla (indipendenti dall'engine).
zenzic init --plugin <nome> genera uno scheletro di pacchetto Python con
entry-point zenzic.rules pronto all'uso e template BaseRule
(src/<modulo>/rules.py). Include anche una fixture docs minima, cosi il
progetto generato puo eseguire subito zenzic check all come smoke test.
Autofix & Cleanup
zenzic clean assets # Elimina gli asset non utilizzati interattivamente (prompt per ognuno)
zenzic clean assets -y # Elimina gli asset non utilizzati immediatamente (senza prompt)
zenzic clean assets --dry-run # Mostra cosa verrebbe eliminato senza farlo
zenzic clean assets rispetta excluded_assets, excluded_dirs e
excluded_build_artifacts da zenzic.toml — non eliminerà mai i file che corrispondono a
questi pattern.
Codici di uscita
| Codice | Significato |
|---|---|
0 | Tutti i controlli selezionati sono passati (o --exit-zero era impostato) |
1 | Uno o più controlli hanno segnalato problemi |
2 | SECURITY CRITICAL — Zenzic Shield ha rilevato una credenziale esposta |
3 | INCIDENTE DI SICUREZZA — Blood Sentinel: il link punta a una directory di sistema dell'OS |
Il codice 2 viene emesso da zenzic check references e zenzic check all quando lo Shield
rileva un pattern di credenziale noto incorporato in un URL di riferimento. Non viene mai
usato per i fallimenti ordinari dei controlli. Se ricevi il codice di uscita 2, trattalo
come un incidente di sicurezza bloccante e ruota immediatamente la credenziale esposta.
Il codice 3 viene emesso quando il Blood Sentinel rileva un link che risolve verso una
directory di sistema dell'OS (/etc/, /root/, /var/, /proc/, /sys/, /usr/).
A differenza del codice 1, questo è un incidente di sicurezza e ha priorità su tutti gli
altri codici di uscita. Non viene mai soppresso da --exit-zero. Consultare
Controlli: Blood Sentinel per i dettagli.
Output JSON
Passa --format json a check all per output strutturato:
zenzic check all --format json | jq '.orphans'
zenzic check all --format json > report.json
Il report JSON contiene sette chiavi:
{
"links": [],
"orphans": [],
"snippets": [],
"placeholders": [],
"unused_assets": [],
"references": [],
"nav_contract": []
}
Ogni chiave contiene una lista di stringhe o oggetti con i problemi. Una lista vuota significa
che il controllo è passato. nav_contract valida i link extra.alternate in mkdocs.yml
rispetto alla Virtual Site Map — sempre vuoto per i progetti non MkDocs.
Comandi singoli
check links, check orphans, check snippets, check references e check assets
accettano ciascuno --format json e restituiscono una struttura uniforme:
zenzic check links --format json
zenzic check references --format json --strict
{
"findings": [
{
"rel_path": "guides/setup.md",
"line_no": 42,
"code": "BROKEN_LINK",
"severity": "error",
"message": "Link target 'install.md' not found"
}
],
"summary": {
"errors": 1,
"warnings": 0,
"info": 0,
"security_incidents": 0,
"security_breaches": 0,
"elapsed_seconds": 0.042
}
}
I codici di uscita sono preservati in modalità JSON: exit 0 quando vengono trovati solo
warning, exit 1 in caso di errori (o warning con --strict), exit 2 per violazioni Shield,
exit 3 per path traversal Blood Sentinel — lo stesso contratto dell'output testuale.
Override dell'engine
Il flag --engine sovrascrive l'adapter del motore di build per una singola esecuzione senza
modificare zenzic.toml. Accettato da check orphans e check all:
zenzic check orphans --engine mkdocs
zenzic check all --engine zensical
zenzic check all --engine vanilla # disabilita il controllo orfani indipendentemente dalla config
Se passi un nome di engine per cui non esiste un adapter registrato, Zenzic elenca gli adapter disponibili ed esce con codice 1:
ERROR: Unknown engine adapter 'hugo'.
Installed adapters: mkdocs, vanilla, zensical
Install a third-party adapter or choose from the list above.
Gli adapter di terze parti vengono scoperti automaticamente una volta installati — nessun aggiornamento Zenzic richiesto. Vedi Scrivere un Adapter.
Punteggio qualità
I controlli individuali rispondono a una domanda binaria: passa o fallisce. zenzic score
risponde a una diversa: quanto è sana questa documentazione, e sta migliorando o peggiorando
nel tempo?
zenzic score # Calcola punteggio 0–100
zenzic score --save # Calcola e persiste snapshot in .zenzic-score.json
zenzic score --fail-under 80 # Esce con 1 se il punteggio è sotto la soglia
zenzic score --format json # Report punteggio machine-readable
zenzic diff # Confronta punteggio attuale con snapshot salvato
zenzic diff --threshold 5 # Esce con 1 solo se il calo è superiore a 5 punti
zenzic diff --format json # Report diff machine-readable
Come è calcolato il punteggio
Ogni categoria di controllo porta un peso fisso che riflette il suo impatto sull'esperienza del lettore:
| Categoria | Peso | Rationale |
|---|---|---|
| links | 35 % | Un link non valido è un vicolo cieco immediato per il lettore |
| orphans | 20 % | Le pagine irraggiungibili sono invisibili — potrebbero non esistere |
| snippets | 20 % | Esempi di codice non validi fuorviano attivamente gli sviluppatori |
| placeholders | 15 % | Il contenuto stub segnala una pagina incompiuta o abbandonata |
| assets | 10 % | Gli asset non usati sono spreco, ma non bloccano il lettore |
All'interno di ogni categoria, il punteggio decade linearmente: il primo problema costa il 20% del peso della categoria, il secondo ne costa altri 20%, con un minimo di zero. Una categoria con cinque o più problemi non contribuisce nulla al totale. I contributi ponderati vengono sommati e arrotondati a un intero.
Tracciare le regressioni
# Sul branch main — stabilisce o aggiorna il baseline
zenzic score --save
# Su ogni pull request — blocca le regressioni della documentazione
zenzic diff --threshold 5
--threshold 5 dà ai collaboratori un margine di cinque punti. Impostalo a 0 per un gate
rigoroso dove qualsiasi regressione fa fallire la pipeline.
Punteggio minimo
zenzic score --fail-under 80
Utile quando il team si è impegnato a mantenere un livello di qualità definito, indipendentemente
da quello che era il punteggio la settimana scorsa. Puoi anche impostare fail_under = 80 in
zenzic.toml per renderlo persistente.
Reporting soft
Per rendere visibile il punteggio senza bloccare la pipeline:
zenzic check all --exit-zero # report completo, esce 0 comunque
zenzic score # mostra il punteggio per visibilità
Ispezione dei plugin
zenzic plugins list # Elenca tutte le regole registrate nel gruppo zenzic.rules
zenzic plugins list mostra ogni regola di linting che il motore conosce — le regole Core
incluse in Zenzic e qualsiasi regola di terze parti installata da pacchetti esterni:
Installed plugin rules (1 found)
broken-links Z001 (core) zenzic.core.rules.VSMBrokenLinkRule
Ogni riga mostra il nome dell'entry-point, il rule_id stabile della regola (usato nei
finding e nelle liste di soppressione), la distribuzione di origine ((core) per le regole
built-in, o il nome del pacchetto per i plugin di terze parti), e il nome completo della
classe Python.
Usa questo comando per verificare quali regole sono attive dopo aver installato un pacchetto plugin.
uvx vs uv run vs zenzic diretto
| Invocazione | Comportamento | Quando usare |
|---|---|---|
uvx zenzic ... | Scarica ed esegue in un ambiente isolato ed effimero | Job una-tantum, pre-commit hook, CI senza fase di install del progetto |
uv run zenzic ... | Esegue dal virtual environment del progetto (richiede uv sync) | Quando Zenzic è in pyproject.toml e serve comportamento version-pinned |
zenzic ... (diretto) | Richiede Zenzic nel $PATH | Macchine developer con install globale |
Preferisci uvx zenzic ... per step CI che non installano già le dipendenze del progetto —
evita di aggiungere Zenzic all'insieme delle dipendenze di produzione.