Guida per Sviluppatori
Benvenuti nella comunità tecnica di Zenzic. Costruiamo strumenti che colmano il
divario tra la documentazione umana e la verità eseguibile. Il nostro codice segue
standard rigorosi per prestazioni, sicurezza dei tipi (mypy --strict) e
accessibilità.
Questa sezione copre tutto il necessario per estendere, adattare o contribuire a Zenzic.
In questa sezione
- Scrivere Regole Plugin — implementa sottoclassi
BaseRule, registrale tramiteentry_pointse soddisfa il contratto pickle / purezza. - Scrivere un Adapter — implementa il protocollo
BaseAdapterper insegnare a Zenzic a gestire un nuovo motore di documentazione. - Progetti di Esempio — quattro fixture eseguibili auto-contenuti che dimostrano configurazioni Zenzic corrette e non.
Workflow Interattivo con Just
Zenzic usa just come command runner interattivo.
just è il layer veloce per il lavoro quotidiano; nox è il layer riproducibile CI
sottostante.
| Comando | Descrizione |
|---|---|
just sync | Installa / aggiorna tutti i gruppi di dipendenze (uv sync --all-groups) |
just check | Auto-lint — esegui Zenzic sulla propria documentazione (strict) |
just test | Esegui la suite di test (delega a nox -s tests, profilo Hypothesis dev) |
just test-full | Esegui la suite di test con profilo Hypothesis ci (500 esempi) |
just preflight | Pipeline completa equivalente a CI: lint, typecheck, test, reuse, sicurezza |
just verify | Gate pre-push: preflight + build-prod |
just build | Build del sito di documentazione (veloce, senza enforcement strict) |
just build-prod | Build del sito di documentazione (modalità strict, rispecchia CI) |
just serve [port] | Avvia il server di documentazione live-reload (porta default 8000) |
just clean | Rimuovi artefatti generati (site/, dist/, .hypothesis/, cache, file score) |
Il dovere di auto-linting della Sentinella — just check — è il primo comando da
eseguire dopo qualsiasi modifica alla documentazione. Esegui just verify prima di
ogni push su main.
Profili Hypothesis
I test property-based usano Hypothesis con
tre profili, controllati dalla variabile d'ambiente HYPOTHESIS_PROFILE:
| Profilo | Esempi per test | Quando usarlo |
|---|---|---|
| dev (default) | 50 | Sviluppo quotidiano (just test) |
| ci | 500 | Pipeline CI e just test-full |
| purity | 1 000 | Validazione esaustiva pre-release |
just test # profilo dev (veloce)
just test-full # profilo ci (approfondito)
HYPOTHESIS_PROFILE=purity just test # pre-release
Mutation testing
Usa nox -s mutation per eseguire mutmut
contro src/zenzic/core/rules.py. Questo non fa parte di just verify
intenzionalmente — eseguilo manualmente dopo aver lavorato sul rule engine:
nox -s mutation
Contribuire
Le linee guida complete per contribuire, le convenzioni del codice, le Core Laws e la
checklist pre-PR si trovano in
CONTRIBUTING.md
su GitHub (in inglese).
Quando apri una pull request, GitHub carica automaticamente la checklist PR — verifica tutte le voci prima di richiedere una revisione.