Passa al contenuto principale

Gestire il Technical Debt

"Perché il mio punteggio è sceso dopo aver ignorato un errore?"

Quando sopprimi un finding in Zenzic — tramite un commento inline o una voce di configurazione per-file — non stai cancellando il problema. Stai assumendoti la responsabilità di esso. Quell'assunzione ha un costo: punti di Technical Debt detratti dal tuo quality score.

Questa guida spiega come leggere il debt, comprendere la formula del costo e ridurlo nel tempo.

Leggere l'Output dello Score​

Dopo aver eseguito zenzic score, potresti vedere una riga aggiuntiva sotto la tabella del punteggio:

Score: 93/100
! Technical Debt (Suppressions): -7 pts
Suppression Audit: 7/30 (inline: 5, per-file: 2)

Questo significa:

  • 7 soppressioni attive stanno nascondendo finding dal flusso di audit.
  • 5 sono commenti zenzic:ignore inline in file Markdown/MDX.
  • 2 sono voci per-file in governance.per_file_ignores.
  • La formula del debt ha ridotto il punteggio di 7 pt.

La Formula del Costo​

extdebt=n ext{debt} = n

Dove:

  • nn = soppressioni attive totali (inline + per-file)
  • cap = governance.suppression_cap in .zenzic.toml (default: 30)

Il costo del debt è flat: ogni soppressione costa sempre 1 pt.

SoppressioniDebtPunteggio (da 100)
00 pt100
1010 pt90
3030 pt70
3131 pt69
3535 pt65

Quando le soppressioni superano il cap configurato, l'esecuzione fallisce comunque tramite il gate di governance (suppression_cap), anche se il debt resta lineare. Il gate di punteggio (fail_under) e il gate del cap sono ortogonali e valutati in modo indipendente.

Passo 1: Vedi Cosa Stai Nascondendo​

Esegui un sovereign audit per vedere tutti i finding attualmente soppressi:

zenzic check all --audit

Il flag --audit bypassa tutti i commenti zenzic:ignore inline e tutte le voci governance.per_file_ignores. Mostra lo stato reale della tua documentazione.

Confronta l'output di --audit con una normale esecuzione di zenzic check all per vedere esattamente quali finding sono nascosti.

Passo 2: Comprendi il Costo della Regola​

Per ogni finding soppresso, usa zenzic explain per vedere il suo impatto sul punteggio:

zenzic explain Z601

L'output mostra:

  • Il tier di scoring della regola (structural / navigation / content / brand)
  • La penalità per occorrenza (pt/occorrenza)
  • Lo stato di soppressione per-file dall'attuale .zenzic.toml

Passo 3: Correggere vs Riconoscere​

Per ogni finding soppresso, prendi una decisione esplicita:

Correggilo (riduci il debt)​

Rimuovi la soppressione e correggi il problema sottostante:

  1. Elimina il commento <!-- zenzic:ignore ZXXX --> dalla riga Markdown.
  2. Oppure rimuovi la voce da governance.per_file_ignores.
  3. Poi correggi la violazione effettiva (aggiorna il link, rimuovi il termine obsoleto, ecc.).
  4. Esegui zenzic check all per verificare.

Riconoscilo (documenta l'intento)​

Se la soppressione è genuinamente intenzionale (riferimento storico, contesto di migrazione, ecc.):

  1. Mantieni la soppressione ma aggiungi un commento in prosa che spiega il perché.
  2. Preferisci la soppressione per-file rispetto ai commenti inline per le eccezioni strutturali — centralizza la policy in .zenzic.toml.
  3. Aggiusta governance.suppression_cap se il tuo progetto ha una baseline di soppressione legittimamente più alta.

Passo 4: Aggiustare il Cap di Governance​

Se il tuo progetto ha una baseline di soppressione consolidata che è superiore a 30, alza il cap in .zenzic.toml:

[governance]
suppression_cap = 45           # aggiustato per un progetto i18n di grandi dimensioni
suppression_cap_fail_hard = true

Impostare il cap al conteggio di soppressione corrente ti dà un floor di governance: le nuove soppressioni aumenteranno immediatamente il costo e alla fine attiveranno suppression_cap_fail_hard.

Perché le Violazioni di Sicurezza Non Possono Essere Soppresse​

I finding nella categoria Security Gate Z2xx — Z201 CREDENTIAL_SECRET, Z202 PATH_TRAVERSAL, Z203 PATH_TRAVERSAL_FATAL e Z204 FORBIDDEN_TERM — non possono essere soppressi con nessun meccanismo.

Un commento <!-- zenzic:ignore: Z201 --> viene silenziosamente ignorato. Il finding viene comunque emesso. L'exit code è comunque 2 o 3. Il punteggio crolla a 0.

Questo è per design. I finding di sicurezza sono fatti, non opinioni di stile. Non puoi assumerti la responsabilità di una perdita di credenziali e chiamarla eccezione validata.

Riferimento​