Registro del Debito Tecnico
"Il debito nascosto corrompe la fiducia. Il debito dichiarato è ingegneria."
Questa pagina è l'elenco pubblico e deliberato delle capacità che Zenzic ha scelto di non rilasciare nella v0.8.x — e il ragionamento ingegneristico che rende ogni rinvio una scelta progettuale consapevole, non una dimenticanza.
La posizione di Zenzic: un progetto che esegue il linting della documentazione altrui deve mantenere uno standard più elevato di onestà sulla propria evoluzione. Ogni voce qui sotto nomina ciò che manca, perché è stato rinviato e quale milestone si fa carico del seguito.
Voci Aperte
Z108 STALE_ALLOWLIST_ENTRY
Categoria: Igiene della configurazione
Stato: Rinviato a v0.8.x
Tracciato: GitHub issue (milestone v0.8.x)
Correlato: ADR 011 (rimosso in v0.8.0)
Cosa è stato rinviato
Un controllo che avvisa quando un prefisso dichiarato in
[link_validation] absolute_path_allowlist non viene mai effettivamente
referenziato da alcun link nel progetto — ovvero la voce di allowlist è
diventata obsoleta e può essere rimossa in sicurezza.
Perché lo abbiamo rinviato
Il controllo è concettualmente diretto ma architetturalmente costoso:
- Violazione del Pillar 3. Z602 e Z105 sono funzioni pure per-link /
per-file — decidono indipendentemente in ogni worker
pytest-xdistsenza stato condiviso. Una determinazione di "usato / non usato" richiede l'aggregazione dei risultati su tutti i file scansionati in tutti i worker, con riconciliazione finale. Introdurre stato aggregato nel pass del validator forzerebbe un ridisegno del Pillar 3 in una release il cui obiettivo dichiarato è consolidamento, non refactor. - Categoria sbagliata. Eseguire il lint del contenuto della documentazione e il lint della configurazione del linter stesso sono spazi problematici differenti. Mescolarli amplia la portata del validator e oscura quali rilevamenti riguardano contenuto utente vs. setup di progetto.
- Segnale YAGNI assente. Non esistono ancora segnalazioni reali di voci di allowlist obsolete. La v0.8.x è la prima release che possiede la funzionalità in assoluto. Aggiungere un controllo di igiene per un problema mai osservato sarebbe prematuro.
Cosa faremo nella
La sede naturale di questo controllo è una superficie dedicata di audit
configurazione all'interno della famiglia di introspezione esistente
(oggi: zenzic config explain): voci di allowlist non referenziate, pattern excluded_dirs
contraddittori, chiavi deprecate, ecc. Questo separa il lint dei
contenuti (pass del validator) dall'audit della configurazione
(pass dell'inspector) e mantiene puri entrambi i pass.
Mitigazione nella
.zenzic.toml è piccolo, versionato e revisionato in code-review ad ogni
PR. Una voce di allowlist obsoleta è una preoccupazione di code-review
nella v0.8.x, promossa a preoccupazione di tooling nella v0.8.x La
finestra di rischio è limitata: una voce obsoleta può al massimo silenziare
un rilevamento Z105 legittimo per un prefisso che non necessita più di
essere silenziato — non può creare falsi positivi, far trapelare dati o
indebolire alcun controllo di sicurezza.
GAP-002 — Supporto Navbar per Plugin Dinamici
Categoria: Scope della validazione link Stato: Rinviato Tracciato: GitHub issue (RFC aperto) Correlato: —
Cosa è stato rinviato
L'adapter Docusaurus di Zenzic analizza docusaurus.config.ts staticamente per
costruire la Virtual Site Map (VSM). Le voci navbar di tipo @docusaurus/plugin-*
— registrate tramite plugin Docusaurus di prima o terza parte — non vengono
parsate. Zenzic ricade sul marcare queste route come REACHABLE, il che significa:
- Rischio falsi positivi: basso — le route generate da plugin raramente risultano rotte.
- Rischio miss: non nullo — orfani reali nascosti dietro voci navbar solo-plugin potrebbero non essere rilevati in configurazioni plugin-heavy.
Perché lo abbiamo rinviato
Le voci navbar dei plugin richiedono la valutazione della configurazione JavaScript del plugin al momento del parse, il che violerebbe l'invariante Nessun Sottoprocesso (Pillar 2). Un parser statico senza stato non può recuperare le route registrate da plugin senza eseguire il plugin stesso.
Cosa faremo
La risoluzione pianificata introduce:
- Un avviso strutturato emesso quando vengono rilevati elementi navbar di plugin, comunicando esplicitamente all'operatore la copertura ridotta.
- Una chiave di configurazione
dynamic_nav_plugins = truein.zenzic.tomlche abilita il riconoscimento esplicito di questa limitazione, sopprimendo l'avviso.
Mitigazione
I progetti Docusaurus plugin-heavy devono assicurarsi che tutte le route generate da plugin compaiano anche in almeno una voce di navigazione non-plugin (sidebar, navbar header, o link diretto da una pagina). Zenzic audita normalmente quei percorsi.
Voci Chiuse
Questa sezione accumulerà voci man mano che gli elementi rinviati vengono rilasciati. Ogni voce chiusa nominerà la versione che l'ha risolta e collegherà la PR mergiata.
(nessuna ancora — la v0.8.x è la prima release con un Registro del Debito Tecnico pubblico.)
Perché esiste questa pagina
Il primo invariante di Zenzic è la Trasparenza. Un linter che nasconde le proprie carenze non è affidabile: ogni progetto che adotta Zenzic dovrebbe poter leggere questo registro e giudicare da sé se il lavoro rinviato è rilevante per il proprio caso d'uso.
Tre impegni governano questa pagina:
- Ogni rinvio viene nominato. Nessun backlog silenzioso. Una capacità considerata e deliberatamente non rilasciata finisce qui.
- Ogni rinvio ha una ragione. "Abbiamo finito il tempo" è accettabile se vero; vaghi giri di parole no. La ragione deve essere sufficientemente specifica perché un futuro contributor possa decidere se il vincolo è ancora valido.
- Ogni rinvio ha un proprietario. Una release target, oppure un esplicito "rinviato a tempo indeterminato" con relativa motivazione. Le voci del registro senza proprietario decadono in folklore.
Quando contribuisci un rinvio qui, non stai ammettendo una debolezza — stai proteggendo il prossimo contributor dal riscoprire lo stesso compromesso.