Design dello Scoring

Razionale di Design

Il Documentation Quality Score (DQS) di Zenzic è deliberatamente rigido su Sicurezza e Governance. L'algoritmo codifica il principio che:

• Un set di documentazione con credenziali trapelate non è un prodotto di qualità a nessun punteggio.
• Un set di documentazione con brand decay incontrollato non può superare 70/100, indipendentemente dall'integrità dei link.

Le violazioni di sicurezza producono un punteggio immediato di 0. Le violazioni di governance ricevono amplificazione esponenziale oltre 10 occorrenze, e un bucket Governance completamente azzerato limita il punteggio totale a 70.

Architettura Dual-Gate

fail_under e suppression_cap operano come vincoli ortogonali valutati indipendentemente:

• Score gate: score < fail_under → zenzic score esce con codice 1
• Governance cap: |Fₛ| > suppression_cap → zenzic score esce con codice 1

Una policy ibrida come fail_under = 90, suppression_cap = 30 impone: "La qualità globale non deve mai scendere sotto 90/100, e indipendentemente dal punteggio, non si tollerano mai più di 30 difetti soppressi."

Poiché ogni soppressione deduce 1 punto (modello flat-cost), il punteggio massimo raggiungibile è:

$\text{Punteggio Max Raggiungibile} = 100 - |F_s|$

dove $|F_s|$ è il conteggio totale delle soppressioni attive. Configurare fail_under > 100 - suppression_cap crea una contraddizione matematica. Regola sicura: fail_under ≤ 100 - suppression_cap.

Esempio Pratico

Scenario: Un repository ha 2 link rotti (Z101), 3 pagine orfane (Z402), 5 blocchi di codice senza tag (Z505) e 15 violazioni brand Z601, con 8 soppressioni attive (cap = 30).

Stage 1 — Security Gate: Nessun finding Z2xx → continua.

Stage 2 — Penalty Table:

Tier	Cap	Deduction	cat_pts
Structural	30	2 × 8.0 = 16.0	14.0
Navigation	25	3 × 4.0 = 12.0	13.0
Content	20	5 × 1.0 = 5.0	15.0
Governance	25	15 × 2.0 = 30.0 → cap a 25	0.0

$S_{\text{base}} = 14 + 13 + 15 + 0 = 42$

Stage 3 — Governance Escalation: 15 violazioni Z601 → $n_{\text{excess}} = 5$ → moltiplicatore $= 2^{5/5} = 2.0$ → deduction $= 30 \times 2 = 60 \to \min(60, 25) = 25$. Bucket brand = 0.

Stage 4 — Gravity Cap: $\text{cat\_pts}_{\text{brand}} = 0$ → $S_{\text{gravity}} = \min(42, 70) = 42$.

Stage 5 — Suppression Debt: $n = 8$ soppressioni → flat-cost: $\omega_{\text{debt}} = 8$.

$S_{\text{final}} = \max(0,\; 42 - 8) = \mathbf{34}$

Leggere l'Output CLI

Il comando zenzic score visualizza un Quality Breakdown Ledger che mostra ogni step aritmetico — dalle penalità per-tier alla cap applicata, l'aggiustamento Gravity Cap, il suppression debt e il punteggio finale.

✨ Quality Score: 65/100

╭─ Quality Breakdown ──────────────────────────────────────╮
│   Category     Issues  Weight  Raw Pts  Applied Pts      │
├──────────────────────────────────────────────────────────┤
│ ✓ structural      0      30%      0           0          │
│ ✓ navigation      0      25%      0           0          │
│ ✗ content         2      20%     -4          -4          │
│ ✗ brand          15      25%    -30         -25 (CAPPED) │
├──────────────────────────────────────────────────────────┤
│   Σ Subtotal                                71           │
╰──────────────────────────────────────────────────────────╯
  ! Technical Debt (6 suppressions)          -6 pts
  = Final Quality Score                      65 / 100

Guida alle colonne:

Colonna	Significato
Raw Pts	Deduction post-escalation prima della cap di categoria, mostrata come valore negativo (o 0).
Applied Pts	Deduction effettivamente sottratta, con cap al massimo del tier.
(CAPPED)	La deduction grezza ha superato la cap del tier ed è stata troncata.
Σ Subtotal	Somma di tutti i valori cat_pts trattenuti prima della Gravity Cap e del Suppression Debt.

Quando scatta la Gravity Cap (Brand bucket = 0), una riga extra appare tra Σ Subtotal e Technical Debt:

│   Σ Subtotal                                75           │
╰──────────────────────────────────────────────────────────╯
  ! Gravity Cap Enforcement (Brand = 0)       -5 pts
  ! Technical Debt (0 suppressions)            0 pts
  = Final Quality Score                       70 / 100

L'aritmetica è sempre esplicita: Σ Subtotal − Gravity Cap − Suppression Debt = Punteggio Finale.

Interpretazione dei Risultati

Finding Informativi

I finding informativi sono diagnostici non bloccanti per visibilità e osservabilità:

• Non riducono il DQS.
• Non attivano mai il Security Override.
• In SARIF vengono emessi al livello note.

Esempi tipici: Z106 (CIRCULAR_LINK), Z114, Z906.

Semantica delle Etichette: [MANAGED DEBT] e [EXTENDED DEBT]

• [MANAGED DEBT]: soppressioni attive presenti e il progetto rimane sul profilo cap sovrano (suppression_cap <= 30).
• [EXTENDED DEBT]: soppressioni attive presenti con un profilo cap espanso (suppression_cap > 30).

Queste etichette descrivono la postura di governance e aiutano i revisori a tracciare la crescita delle soppressioni nel tempo.

Ispezione della Postura di Soppressione

zenzic score            # visualizza la postura corrente nel Quality Breakdown Ledger
zenzic check all --audit  # visualizza tutti i finding senza soppressioni applicate