diff --git a/Analisi-repository-API-Collections.md b/Analisi-repository-API-Collections.md new file mode 100644 index 0000000..80cc241 --- /dev/null +++ b/Analisi-repository-API-Collections.md @@ -0,0 +1,187 @@ +# Analisi repository API Collections + +## Esito + +Il repository ha un’architettura semplice e appropriata allo scopo, ma la pipeline Bruno → httpyac non è sufficientemente protetta. I rischi principali sono: + +1. esempi versionati contenenti dati personali e identificativi di sessione; +2. conversioni httpyac incomplete o incompatibili; +3. tre file YAML non validi per il parser usato dal progetto; +4. test e quality gate quasi assenti. + +Non serve una riscrittura generale: gli interventi possono essere incrementali e concentrati sui confini di conversione e validazione. + +## Struttura e dipendenze + +```text +bruno/workspace.yml + └─ 11 collezioni Bruno / 272 richieste circa + ├─ folder e configurazioni ereditate + ├─ ambienti e template dei segreti + ├─ script Bruno + └─ esempi di request/response versionati + +env.json.template + └─ setup-json-environment.ps1 → env.json locale + ├─ update-bruno-environments.ps1 → .env Bruno + └─ update-httpyac-environments.ps1 → .env httpyac + +bruno/ + └─ generate-httpyac-requests.ps1 → autodocs/httpyac/ ignorato da Git +``` + +Dipendenze esterne: + +- PowerShell ≥ 7.5; +- modulo `powershell-yaml`, disponibile localmente in versione 0.4.12; +- Bruno; +- estensione/CLI httpyac, non disponibile nella shell esaminata. + +`tools/generate-http-requests/node_modules` è un artefatto locale ignorato, senza manifest versionato, e non costituisce una dipendenza riproducibile del repository. + +## Quality gate e test attuali + +Non risultano configurati CI, Pester, PSScriptAnalyzer, linting, coverage, scansione dei segreti o validazione automatica delle collezioni. + +Controlli read-only eseguiti: + +- 5 script PowerShell analizzati: zero errori sintattici; +- 338 file YAML analizzati con `powershell-yaml`; +- 3 YAML non validi; +- 269 richieste analizzabili: 129 GET, 118 POST, 17 PUT, 3 DELETE, 2 PATCH; +- 140 richieste mutative analizzabili; +- solo 4 delle 140 richieste mutative hanno una definizione di test a livello di richiesta; +- i 7 `.env.template` sono attualmente sincronizzati con `env.json.template`; +- nessuna suite automatizzata eseguibile; +- PSScriptAnalyzer e httpyac CLI non presenti. + +Gli `examples` presenti nelle collezioni sono snapshot, non test. Lo stato complessivo dei gate è quindi **non superato/non definito**: manca un gate ufficiale e la validazione YAML già fallisce. + +## Backlog tecnico prioritizzato + +Costo indicativo: **S** < 1 giorno, **M** 1–3 giorni, **L** > 3 giorni. + +### 1. Dati personali e cookie di sessione negli esempi versionati + +- **Severità/costo:** Critica / M +- **File/modulo:** esempi Bruno, per esempio [Get Items.yml]() e [Get UserInfo.yml](). +- **Problema:** rilevati identificativi compatibili con codici fiscali in 38 file e cookie/session ID in 20 file. Alcuni esempi includono anche nomi e informazioni organizzative. Il file più grande supera 5,3 MB e 134.000 righe. +- **Rischio:** esposizione di dati personali, conservazione indefinita nella cronologia Git, possibili credenziali di sessione ancora utilizzabili, forte rumore nelle review. +- **Intervento minimo:** verificare l’origine dei dati, invalidare eventuali sessioni ancora valide, redigere o sostituire con dati sintetici gli esempi; limitare gli snapshot alle proprietà indispensabili. +- **Test prima dell’intervento:** introdurre una scansione ripetibile per cookie, token e identificativi personali con allowlist esplicita; registrare il baseline prima della redazione. +- **Impatto architetturale:** trasversale sulla politica di gestione degli esempi, senza nuovi layer. + +### 2. Tre collezioni non sono parseabili dal convertitore dichiarato + +- **Severità/costo:** Alta / S +- **File/modulo:** [Backoffice - Dashboard.yml](), [Login - Backoffice.yml](), [Login - Gestione Schede.yml](). +- **Problema:** i literal block contengono righe iniziali whitespace-only che `powershell-yaml` rifiuta. Il generatore propaga l’errore da [Parse-Yaml](C:/_Git/UniPR/api-collections/scripts/generate-httpyac-requests.ps1:26). +- **Rischio:** generazione httpyac interrotta e output parziale o obsoleto. +- **Intervento minimo:** normalizzare quei blocchi e fare fallire il comando con un riepilogo completo dei file invalidi. +- **Test prima dell’intervento:** gate che esegua il parsing di tutti i YAML; fixture con il blocco problematico e verifica dell’errore diagnostico. +- **Impatto architetturale:** nessuno; rende affidabile il formato sorgente. + +### 3. Script Bruno copiati in httpyac senza adattamento del runtime + +- **Severità/costo:** Alta / M +- **File/modulo:** [Parse-HttpBlock](C:/_Git/UniPR/api-collections/scripts/generate-httpyac-requests.ps1:206) e [Build-RequestContent](C:/_Git/UniPR/api-collections/scripts/generate-httpyac-requests.ps1:738). +- **Problema:** 16 file `.http` generati contengono chiamate Bruno come `bru.setVar` e `res.getStatus()`. httpyac documenta invece oggetti quali `response`, `$global` ed `exports`; la copia verbatim attraversa impropriamente il confine tra due runtime diversi. [Documentazione ufficiale httpyac](https://httpyac.github.io/guide/scripting.html) +- **Rischio:** request apparentemente generate ma script e test non eseguibili. +- **Intervento minimo:** tradurre solo le API Bruno effettivamente usate oppure interrompere esplicitamente la conversione dei file non supportati, evitando output silenziosamente difettoso. +- **Test prima dell’intervento:** golden test per login, lettura risposta e salvataggio variabile; esecuzione del `.http` generato contro un endpoint mock. +- **Impatto architetturale:** importante sul boundary Bruno→httpyac, ma confinato all’adapter esistente. + +### 4. I body `multipart-form` vengono ignorati + +- **Severità/costo:** Alta / M +- **File/modulo:** [Build-RequestContent](C:/_Git/UniPR/api-collections/scripts/generate-httpyac-requests.ps1:693); richieste interessate includono [AJ Console - Save Object.yml](), [Backoffice - Create Group.yml]() e Login Backoffice. +- **Problema:** il generatore implementa soltanto `json` e `form-urlencoded`; per multipart emette una POST senza body e senza segnalazione. +- **Rischio:** operazioni mutative errate, con comportamento molto diverso dalla richiesta Bruno. +- **Intervento minimo:** supportare multipart per i campi realmente presenti oppure fallire esplicitamente indicando request e body type. +- **Test prima dell’intervento:** fixture multipart con campi testo, placeholder e caratteri speciali; confronto golden del body generato. +- **Impatto architetturale:** locale al convertitore. + +### 5. Aree mutative quasi prive di protezione automatica + +- **Severità/costo:** Alta / L +- **File/modulo:** soprattutto `Cambio stato e-o integrazione`, `Console UI`, ESSE3 e i 93 POST EFTL. +- **Problema:** soltanto 4 delle 140 richieste mutative analizzabili hanno test request-level; non esiste un comando CI che li esegua. +- **Rischio:** regressioni su cambio stato, clone, aggiornamenti, delete e autenticazione scoperte soltanto manualmente. +- **Intervento minimo:** partire da smoke/contract test per autenticazione e operazioni più distruttive, usando ambienti controllati o mock; non è necessario testare subito ogni snapshot. +- **Test prima dell’intervento:** definire una matrice minima per status, payload obbligatori, errori 4xx e assenza di effetti collaterali indesiderati. +- **Impatto architetturale:** introduce un gate, non un nuovo layer applicativo. + +### 6. Serializzazione `.env` non round-trip safe + +- **Severità/costo:** Alta / S +- **File/modulo:** [update-bruno-environments.ps1](C:/_Git/UniPR/api-collections/scripts/update-bruno-environments.ps1:29) e [update-httpyac-environments.ps1](C:/_Git/UniPR/api-collections/scripts/update-httpyac-environments.ps1:26). +- **Problema:** i valori contenenti `#` vengono quotati, ma il parser conserva le quote; una seconda esecuzione può produrre quote duplicate. Apici, newline e altri caratteri dotenv non vengono gestiti sistematicamente. +- **Rischio:** password e token validi diventano inutilizzabili senza errore esplicito. +- **Intervento minimo:** definire escaping e parsing simmetrici per il sottoinsieme dotenv supportato. +- **Test prima dell’intervento:** round-trip parametrico per `#`, apici, spazi, `=`, valori vuoti e `null`. +- **Impatto architetturale:** boundary dei segreti; nessun nuovo layer necessario. + +### 7. Test errato e dead code nello script “owners” + +- **Severità/costo:** Media / S +- **File/modulo:** [SCRIPT - Get Contracts with two or more owners.yml](). +- **Problema:** l’output espone `ownersCount`, ma il test verifica `contributorCount` alla [riga 248](). Il controllo `output.length >= 0` alla riga 258 è tautologico. Rimane inoltre un intero ramo contributor commentato e una funzione department non più utilizzata. +- **Rischio:** fallimenti ingannevoli o test che passano senza verificare l’aggregazione; manutenzione confusa. +- **Intervento minimo:** correggere la proprietà, usare una fixture non vuota e rimuovere il ramo commentato dopo aver verificato che non sia necessario. +- **Test prima dell’intervento:** dataset con zero, uno e più owners e paginazione multipla. +- **Impatto architetturale:** nessuno; elimina una conseguenza concreta del copy/paste. + +### 8. Generatore troppo concentrato e accoppiato al nome della cartella EFTL + +- **Severità/costo:** Media / M +- **File/modulo:** [generate-httpyac-requests.ps1](C:/_Git/UniPR/api-collections/scripts/generate-httpyac-requests.ps1:420). +- **Problema:** 1.095 righe; `Build-RequestContent` è di 377 righe con circa 63 diramazioni. Il comportamento EFTL è attivato cercando `"EFTL processing"` nel percorso e sovrascrive indiscriminatamente il post-response script alle [righe 733–785](C:/_Git/UniPR/api-collections/scripts/generate-httpyac-requests.ps1:733). Inoltre `Parse-Workspace` reimplementa manualmente il parsing pur essendo già disponibile il parser YAML. +- **Rischio:** cambiamenti locali producono regressioni trasversali; rinominare una cartella cambia la semantica. +- **Intervento minimo:** aggiungere test di caratterizzazione e separare soltanto rendering di auth, body e script in funzioni pure; rendere esplicita la modalità EFTL nella configurazione. +- **Test prima dell’intervento:** golden test EFTL/non-EFTL, inclusi script senza marker o marker incompleti. +- **Impatto architetturale:** chiarisce il confine tra conversione generica e regola EFTL senza introdurre pattern ulteriori. + +### 9. Duplicazione degli updater e variabili dipendenti da rami precedenti + +- **Severità/costo:** Media / M +- **File/modulo:** i due `update-*-environments.ps1`, differenti per appena 15 aggiunte e 18 rimozioni. +- **Problema:** `$sectionKeys` viene inizializzata dentro il ramo che trova `.env.template`, ma può essere usata successivamente anche quando il template manca. La duplicazione rende facile correggere un solo updater. +- **Rischio:** chiavi mancanti, riuso accidentale dei valori dell’iterazione precedente e divergenza Bruno/httpyac. +- **Intervento minimo:** prima inizializzare sempre le chiavi; poi usare un’unica funzione parametrizzata per root e policy di esclusione. +- **Test prima dell’intervento:** template presente/assente, `.env` presente/assente, chiavi aggiunte/rimosse e valori `null`. +- **Impatto architetturale:** riduce duplicazione di conoscenza nella pipeline dei segreti. + +### 10. Bootstrap delle dipendenze non riproducibile + +- **Severità/costo:** Media / S +- **File/modulo:** [setup-tools.ps1](C:/_Git/UniPR/api-collections/scripts/setup-tools.ps1:1) e [README.md](C:/_Git/UniPR/api-collections/README.md:18). +- **Problema:** il README promette un tentativo di installazione, ma lo script esegue solo `Import-Module ... -ErrorAction SilentlyContinue` e comunica comunque successo. Non è dichiarata una versione compatibile. +- **Rischio:** una nuova workstation fallisce più avanti con diagnostica poco chiara. +- **Intervento minimo:** verificare presenza/versione e terminare con istruzioni esplicite oppure installare soltanto previo consenso dell’utente. +- **Test prima dell’intervento:** esecuzione in una sessione senza modulo e con versione incompatibile. +- **Impatto architetturale:** dependency hygiene, nessun cambiamento strutturale. + +### 11. Copie e contenuti obsoleti aumentano il rischio di deriva + +- **Severità/costo:** Bassa / S–M +- **File/modulo:** directory `OLD`, `Obsolete`, file `Get Items Copy.yml`/`Get ASNs Copy.yml` e due coppie di runner completamente identiche. +- **Problema:** duplicazione significativa e snapshot molto grandi; non è però dimostrabile dalla sola analisi statica che siano davvero inutilizzati. +- **Rischio:** correzioni applicate a una sola copia, review lente e crescita del repository. +- **Intervento minimo:** censire uso e ownership; eliminare solo copie confermate inutilizzate o documentarne esplicitamente lo scopo. +- **Test prima dell’intervento:** confronto comportamentale delle copie e verifica con gli utilizzatori. +- **Impatto architetturale:** nessuno; pulizia controllata, non refactoring speculativo. + +## Invarianti consigliate + +I futuri gate dovrebbero verificare almeno che: + +- ogni YAML sia parseabile dal parser effettivamente usato; +- nessun body type venga ignorato silenziosamente; +- gli script attraversino Bruno→httpyac solo se tradotti o dichiarati compatibili; +- gli output generati siano prodotti in una directory temporanea e validati; +- i template dei segreti restino sincronizzati; +- esempi e snapshot non contengano credenziali o dati personali non autorizzati. + +Non raccomando al momento un ADR formale: basterebbe documentare queste invarianti nel repository e automatizzarle. + +Non ho letto il contenuto di `env.json`, non ho eseguito chiamate API e non ho lanciato script che scrivono output. `git status` e `git diff` sono rimasti vuoti: nessun file è stato modificato. \ No newline at end of file