api-collections/Analisi-repository-API-Collections.md

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

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.
• 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 e Build-RequestContent.
• 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
• 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; 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 e update-httpyac-environments.ps1.
• 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.
• 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. 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 e README.md.
• 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.