Il quantum-core-report.ps1 non è solo uno script che conta le righe di codice. È il cuore del nostro sistema di “Documentazione Vivente”. La sua funzione principale è trasformare i metadati che inseriamo diligentemente nei nostri file sorgente (il “File Header Block” della Regola 5) in un cruscotto architetturale dinamico e interrogabile.
Invece di affidarci a diagrammi statici che diventano obsoleti, usiamo questo strumento per avere una fotografia accurata dello stato del progetto in qualsiasi momento. Lo script è la ricompensa per la nostra disciplina nel documentare: trasforma un piccolo sforzo individuale in un enorme vantaggio collettivo.
2. Funzionalità Chiave: Cosa Fa lo Script?
Lo script esegue una scansione completa del progetto per:
Parsing dei Metadati: Legge l’header di ogni file per estrarre VERSION, RESP, DEPS, ARCH_ROLE e LAYER.
Analisi Quantitativa: Calcola metriche essenziali come il numero di file, le righe di codice e la dimensione dei moduli.
Mappatura Architetturale:
Crea una panoramica dei moduli principali (ARCHITECTURAL OVERVIEW).
Classifica i componenti chiave in base al loro ruolo (framework, connector), fornendo una mappa immediata delle fondamenta del sistema.
Analizza le dipendenze per costruire un grafo delle relazioni tra i file.
Diagnostica della Salute del Codice: Identifica proattivamente i rischi architetturali e il technical debt, tra cui:
God Objects: File che hanno troppe dipendenze in entrata, rendendoli rischiosi da modificare.
Dipendenze Circolari: Un “red flag” critico che indica un design problematico.
Moduli/File Complessi Non Documentati: Evidenzia le aree ad alto rischio che necessitano di attenzione immediata.
File Orfani: Potenziali candidati per essere rimossi (dead code).
Generazione di Report Flessibile: Produce un output in formato .txt in due modalità principali per adattarsi a diverse esigenze.
3. Guida Pratica: Come si Usa
Lo script va eseguito da un terminale PowerShell nella root del progetto.
Uso Base (Modalità Compatta)
Questo è il comando da usare il 99% delle volte per avere una rapida visione d’insieme.
.\quantum-core-report_v9.ps1
Cosa fa: Genera un file project_report.txt nella directory corrente. Il report è in modalità compatta, ottimizzata per una lettura veloce, ma include già la sezione critica sui componenti framework e connector.
Uso Avanzato (Modalità Completa)
Da usare quando hai bisogno di un’analisi enciclopedica di ogni singolo file.
.\quantum-core-report_v9.ps1 -FullReport
Cosa fa: Genera un report completo con la struttura ad albero espansa, il dettaglio di tutti i file e l’analisi completa delle dipendenze.
Questo aggiungerà alla fine del report un blocco di testo formattato per Mermaid.js, che puoi incollare in un editor compatibile (come Obsidian o la web preview di GitHub) per visualizzare il grafo delle dipendenze.
4. Anatomia del Report: Come Leggerlo Efficacemente
Il report è strutturato in tre livelli di priorità per guidare la tua attenzione.
Livello 1: 🚀 [CRUSCOTTO] - Leggi Subito
Questa è la sezione più importante. Se hai solo 5 minuti, leggi questa.
PROJECT SUMMARY: Le metriche vitali.
PUNTI CRITICI DI ATTENZIONE: Il “check-engine” del tuo progetto. Se ci sono “God Objects” o dipendenze circolari, lo vedi qui.
FILE PIÙ COMPLESSI: I file più grandi, che sono spesso i più difficili da mantenere.
ARCHITECTURAL OVERVIEW: I moduli principali per dimensione, per capire dove si concentra il codice.
COMPONENTI CHIAVE PER RUOLO ARCHITETTURALE:La mappa del tesoro. Ti mostra subito i file framework e connector, ovvero le fondamenta e i ponti del tuo sistema.
Livello 2: 🗺️ [CONTESTO] - Consulta Dopo il Cruscotto
Questa sezione fornisce maggiori dettagli per orientarti.
STRUTTURA AD ALBERO: La visione della struttura delle directory.
ALTRI COMPONENTI RILEVANTI: Una lista dei file feature e utility più importanti per dimensione e documentazione.
Livello 3: 📚 [REFERENCE MATERIAL] - Cerca al Bisogno
Questa è l’enciclopedia. Usala quando hai bisogno di un’informazione specifica.
PANORAMICA DEL TECHNICAL DEBT (TODO): La lista completa di tutti i # TODO lasciati nel codice.
ANALISI DELLE DIPENDENZE INVERSE: La lista completa di chi usa cosa. Utile per valutare l’impatto di una modifica.
DETTAGLIO COMPLETO DEI COMPONENTI (solo in -FullReport): La scheda dettagliata di ogni singolo file del progetto.
5. L’Utilità Pratica: Perché Questo Strumento è Fondamentale?
Onboarding Accelerato: Un nuovo sviluppatore può eseguire lo script e capire l’architettura fondamentale del progetto in meno di 10 minuti, concentrandosi sui file framework.
Supporto alle Decisioni Architetturali: Prima di aggiungere una nuova funzionalità, il report ti aiuta a decidere dove collocare il nuovo codice e quali componenti framework riutilizzare.
Manutenzione Proattiva: Identifica i problemi di salute del codice prima che diventino critici, guidando gli sforzi di refactoring.
Coerenza del Team: Incoraggia e “premia” la pratica di mantenere la documentazione aggiornata, allineando tutto il team sullo stesso standard.