Skip to content

docs: sync READMEs and CITATION.cff with v0.5.0a4 post-release #35

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
PythonWoods-Dev merged 1 commit into from
Apr 8, 2026
Merged

docs: sync READMEs and CITATION.cff with v0.5.0a4 post-release #35

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion CITATION.cff
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ abstract: >
source-first — no build framework required — and integrates with any Markdown-based
documentation system via a plugin adapter protocol.
version: 0.5.0a4
date-released: 2026-04-03
date-released: 2026-04-08
url: "https://zenzic.pythonwoods.dev/"
repository-code: "https://github.com/PythonWoods/zenzic"
license: Apache-2.0
Expand Down
66 changes: 33 additions & 33 deletions README.it.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ SPDX-License-Identifier: Apache-2.0

<p align="center">
<a href="https://pypi.org/project/zenzic/">
<img src="https://img.shields.io/pypi/v/zenzic?include_prereleases&label=PyPI&color=38bdf8&style=flat-square&cacheBuster=sentinel-a3" alt="PyPI Version">
<img src="https://img.shields.io/pypi/v/zenzic?include_prereleases&label=PyPI&color=38bdf8&style=flat-square&cacheBuster=sentinel-a4" alt="PyPI Version">
</a>
<a href="https://pypi.org/project/zenzic/">
<img src="https://img.shields.io/pypi/pyversions/zenzic?color=10b981&style=flat-square" alt="Python Versions">
Expand Down Expand Up @@ -64,31 +64,28 @@ gli altri strumenti citati sono progetti di terze parti.

---

## v0.5.0a3 — La Sentinella

- **Inizializzazione Intelligente**: `zenzic init` rileva `pyproject.toml` e offre di
incorporare la configurazione come `[tool.zenzic]` invece di creare un `zenzic.toml`
separato. Usa `--pyproject` per saltare il prompt. Auto-detection dell'engine in
entrambe le modalità.
- **Sentinel UI**: banner Indigo monolitico, gutter traceback con spaziatura a 2 spazi
(`│ 16 ❱`), sottolineature caret chirurgiche e respiro verticale tra i finding.
- **Target Agnostico**: `zenzic check all README.md` o `zenzic check all content/`
limita l'audit a un singolo file o directory. `VanillaAdapter` selezionato
automaticamente per target fuori da docs.
- **Plugin SDK**: `zenzic init --plugin <nome>` scaffolda un pacchetto regole
pronto all'uso. Namespace pubblico `zenzic.rules` stabile — `BaseRule`,
`RuleFinding`, `CustomRule`, `Violation`, `Severity`.
- **Hybrid Adaptive Engine**: `scan_docs_references` seleziona esecuzione sequenziale
o parallela automaticamente in base alla dimensione del repository (soglia: 50 file).
Validazione ancore deterministica a due fasi elimina falsi positivi da race condition.
- **Z001/Z002 Split**: link rotti (Z001 errore) vs link a pagine orfane (Z002 warning).
Senza `--strict`, i warning orfani non bloccano la build.
- **Mutation-tested**: 86.7% mutation score (242/279 killed su `rules.py`).
706 test, Hypothesis property-based testing con profili tiered.
- **Config `pyproject.toml`**: incorpora la configurazione Zenzic in `[tool.zenzic]`
quando `zenzic.toml` è assente. `zenzic.toml` vince sempre se entrambi esistono.
- **Zenzic Shield**: rilevamento credenziali (7 famiglie) + protezione path traversal.
Codice di uscita 2 riservato per eventi di sicurezza.
## v0.5.0a4 — La Sentinella Blindata

- **Sentinella di Sangue (Exit Code 3)**: I link che escono da `docs/` e puntano a
directory di sistema del SO (`/etc/`, `/root/`, `/var/`, `/proc/`, `/sys/`, `/usr/`)
vengono classificati come `security_incident` e terminano con codice **3**. Priorità:
`3 > 2 (Shield) > 1 (errori)`. Non soppresso da `--exit-zero`.
- **Graph Integrity (Θ(V+E))**: Rilevamento dei link circolari tramite DFS iterativa
sull'intero grafo di link interni. Costruito una sola volta (Fase 1.5); ogni query
della Fase 2 è O(1). `CIRCULAR_LINK` è advisory (severità `info`) — i link di
navigazione reciproca sono struttura valida e non bloccano mai la CI.
- **Hex Shield**: Lo Shield ora rileva payload hex-encoded — 3 o più sequenze `\xNN`
consecutive — intercettando credenziali offuscate nei blocchi di codice.
- **Controllo Rumore (`--show-info`)**: I finding informativi sono soppressi per
default. Una nota a piè di pagina li conta: *"N info findings suppressed — usa
--show-info per i dettagli."* Disponibile su tutti i 7 comandi di check.
- **ZRT-005 Risolto — Bootstrap Paradox**: `zenzic init` funziona ora correttamente
in una directory completamente vuota. Il `zenzic.toml` generato include un blocco
Shield commentato con tutte le 8 famiglie di pattern rilevate.
- **Rigore Bilingue**: Parità di documentazione raggiunta tra Inglese e Italiano.
`checks.md`, `arch_gaps.md`, `architecture.md` e `INTERNAL_GLOSSARY.toml` (15
termini canonici) ora disponibili in entrambe le lingue.
- **759 test. Preflight verde.**

---

Expand Down Expand Up @@ -227,15 +224,18 @@ zenzic serve --port 9000
| `0` | Tutti i controlli selezionati sono passati |
| `1` | Uno o più controlli hanno segnalato problemi |
| **`2`** | **SECURITY CRITICAL — Zenzic Shield ha rilevato una credenziale esposta** |
| **`3`** | **SECURITY CRITICAL — Sentinella di Sangue ha rilevato un path traversal di sistema** |

> **Attenzione:**
> Il **codice di uscita 2** è riservato esclusivamente agli eventi di sicurezza. Se
> `zenzic check references` esce con codice 2, una credenziale è stata trovata nella
> documentazione. Ruotare la credenziale immediatamente.

Lo **Zenzic Shield** rileva 7 famiglie di credenziali (chiavi OpenAI, token GitHub, access key
AWS, chiavi live Stripe, token Slack, chiavi API Google e chiavi private PEM) su **ogni riga del
file sorgente** — incluse le righe dentro i blocchi di codice `bash`, `yaml` e senza etichetta.
> Il **codice di uscita 2** è riservato agli eventi Shield (credenziali esposte). Il **codice
> di uscita 3** è riservato alla Sentinella di Sangue (path traversal verso directory di sistema
> come `/etc/`, `/root/`). Entrambi non vengono mai soppressi da `--exit-zero`. Ruotare e
> verificare immediatamente.

Lo **Zenzic Shield** rileva 8 famiglie di credenziali (chiavi OpenAI, token GitHub, access key
AWS, chiavi live Stripe, token Slack, chiavi API Google, chiavi private PEM e payload
hex-encoded) su **ogni riga del file sorgente** — incluse le righe dentro i blocchi di codice
`bash`, `yaml` e senza etichetta.
Una credenziale in un esempio di codice è comunque una credenziale esposta.

---
Expand Down
59 changes: 29 additions & 30 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ SPDX-License-Identifier: Apache-2.0

<p align="center">
<a href="https://pypi.org/project/zenzic/">
<img src="https://img.shields.io/pypi/v/zenzic?include_prereleases&label=PyPI&color=38bdf8&style=flat-square&cacheBuster=sentinel-a3" alt="PyPI Version">
<img src="https://img.shields.io/pypi/v/zenzic?include_prereleases&label=PyPI&color=38bdf8&style=flat-square&cacheBuster=sentinel-a4" alt="PyPI Version">
</a>
<a href="https://pypi.org/project/zenzic/">
<img src="https://img.shields.io/pypi/pyversions/zenzic?color=10b981&style=flat-square" alt="Python Versions">
Expand Down Expand Up @@ -63,31 +63,28 @@ referenced ecosystem tools are third-party projects.

---

## v0.5.0a3 Highlights — The Sentinel

- **Smart Initialization**: `zenzic init` detects `pyproject.toml` and offers to
embed config as `[tool.zenzic]` instead of a standalone `zenzic.toml`. Use
`--pyproject` to skip the prompt. Engine auto-detection in both modes.
- **Sentinel UI**: monolithic Indigo banner, traceback gutter with 2-space
padding (`│ 16 ❱`), surgical caret underlines, and vertical breathing
between findings.
- **Agnostic Target**: `zenzic check all README.md` or `zenzic check all content/`
scopes audits to a single file or directory. `VanillaAdapter` auto-selected for
out-of-docs targets.
- **Plugin SDK**: `zenzic init --plugin <name>` scaffolds a ready-to-edit rule
package. `zenzic.rules` public namespace is stable — `BaseRule`, `RuleFinding`,
`CustomRule`, `Violation`, `Severity`.
- **Hybrid Adaptive Engine**: `scan_docs_references` selects sequential or parallel
execution automatically based on repository size (threshold: 50 files).
Deterministic two-phase anchor validation eliminates race-induced false positives.
- **Z001/Z002 Split**: broken links (Z001 error) vs orphan-page links (Z002 warning).
Without `--strict`, orphan warnings don't block the build.
- **Mutation-tested**: 86.7% mutation score (242/279 killed on `rules.py`).
706 tests, Hypothesis property-based testing with tiered profiles.
- **`pyproject.toml` config**: embed Zenzic config in `[tool.zenzic]` when
`zenzic.toml` is absent. `zenzic.toml` always wins if both exist.
- **Zenzic Shield**: credential detection (7 secret families) + path traversal
protection. Exit code 2 reserved for security events.
## v0.5.0a4 Highlights — The Hardened Sentinel

- **Blood Sentinel (Exit Code 3)**: Path traversal links that escape `docs/` and
target OS system directories (`/etc/`, `/root/`, `/var/`, `/proc/`, `/sys/`,
`/usr/`) are classified as `security_incident` and exit with code **3**. Priority
order: `3 > 2 (Shield) > 1 (errors)`. Never suppressed by `--exit-zero`.
- **Graph Integrity (Θ(V+E))**: Circular link detection via iterative DFS over the
full internal link graph. Built once (Phase 1.5); every Phase 2 per-query lookup
is O(1). `CIRCULAR_LINK` is advisory (`info` severity) — mutual navigation links
are valid documentation structure and never block CI.
- **Hex Shield**: The Shield now detects hex-encoded payloads — 3 or more consecutive
`\xNN` escape sequences — catching obfuscated credentials inside fenced code blocks.
- **Signal-to-Noise Control (`--show-info`)**: Advisory findings are suppressed by
default. A footer note counts them: *"N info findings suppressed — use --show-info
for details."* Available on all 7 check commands.
- **ZRT-005 Fixed — Bootstrap Paradox**: `zenzic init` now works correctly in a
completely empty directory. The generated `zenzic.toml` includes a commented Shield
block listing all 8 detected credential pattern families.
- **Bilingual Rigor**: Full documentation parity achieved across English and Italian.
`checks.md`, `arch_gaps.md`, `architecture.md`, and `INTERNAL_GLOSSARY.toml` (15
canonical terms) are now available in both languages.
- **759 tests. Preflight green.**

---

Expand Down Expand Up @@ -419,11 +416,12 @@ zenzic serve --no-preflight
| `0` | All selected checks passed |
| `1` | One or more checks reported issues |
| **`2`** | **SECURITY CRITICAL — Zenzic Shield detected a leaked credential** |
| **`3`** | **SECURITY CRITICAL — Blood Sentinel detected a system-path traversal** |

> **Warning:**
> **Exit code 2** is reserved exclusively for security events. If `zenzic check references` exits
> with code 2, a secret (OpenAI API key, GitHub token, or AWS access key) was found embedded in a
> reference URL inside your documentation. Rotate the credential immediately.
> **Exit code 2** is reserved for Shield events (leaked credentials). **Exit code 3** is
> reserved for Blood Sentinel events (path traversal to OS system directories such as
> `/etc/`, `/root/`). Both are never suppressed by `--exit-zero`. Rotate and audit immediately.

---

Expand Down Expand Up @@ -463,7 +461,7 @@ Build aborted. Rotate the exposed credential immediately.
1. The Shield runs *inside* Pass 1 — before Pass 2 validates links and before any HTTP ping is
issued. A document containing a leaked credential is never used to make outbound requests.
2. Patterns use exact-length quantifiers (`{48}`, `{36}`, `{16}`) — no backtracking, O(1) per line.
3. Seven credential families are covered out of the box:
3. Eight credential families are covered out of the box:

| Type | Pattern |
| --- | --- |
Expand All @@ -474,6 +472,7 @@ Build aborted. Rotate the exposed credential immediately.
| Slack token | `xox[baprs]-[0-9a-zA-Z]{10,48}` |
| Google API key | `AIza[0-9A-Za-z\-_]{35}` |
| PEM private key | `-----BEGIN [A-Z ]+ PRIVATE KEY-----` |
| Hex-encoded payload | 3+ consecutive `\xNN` escape sequences |

1. **No blind spots** — the Shield scans every line of the source file, including lines inside
fenced code blocks (`bash`, `yaml`, unlabelled, etc.). A credential committed inside a code
Expand Down