Come costruire l'intelligenza del codice a livello del repository con Repowise usando analisi grafica, rilevamento codice morto, decisioni e contesto AI

Costruire l'intelligenza del codice a livello di repository rappresenta un passo importante per mantenere l'efficacia e l'efficienza del processo di sviluppo in progetti software di grandi dimensioni. Questo articolo illustra la pratica implementazione di questa intuizione tramite l'utilizzo di Repowise per analizzare il progetto Python "itsdangerous". Verrà spiegato come configurare Repowise, come eseguire l'indice del repository, e come utilizzare strumenti avanzati come l'analisi grafica, rilevamento di codice morto, e l'inserimento di decisioni architetturali. Inoltre, si mostrerà come ottenere informazioni contestuali tramite interazioni con modelli LLM.

Configurazione iniziale

Per iniziare, si importano le librerie necessarie (come os, sys, json, subprocess) e si definiscono funzioni utili:

• sh: per eseguire comandi shell e catturare output;
• banner: per stampare titoli visibili per ogni sezione del tutorial;

Nel contesto della cartella del repository itsdangerous si configura una struttura di esecuzione pulita per gestire il percorso di lavoro e l'ambiente. Le librerie come NetworkX, Shutil, e TextWrap forniscono strumenti fondamentali per manipolare e visualizzare dati grafici nonché testi a schermo.

Inizializzazione del progetto Repowise

Per configurare Repowise, si esegue il comando repowise --version e repowise init --help per verificare la corretta installazione e mostrare opzioni disponibili. Successivamente, si seleziona automaticamente un modello di intelligenza artificiale in base alla presenza delle chiavi API (Anthropic o OpenAI). Si genera il file di configurazione .repowise/config.yaml e si lancia l'indice del progetto, che può essere avviato con --index-only se necessario. Qualora non vada a buon fine, vengono fornite indicazioni per risolvere gli errori.

Struttura e analisi degli artefatti Repowise

Dopo l'inizializzazione, Repowise genera una directory .repowise con diversi artefatti, utili per comprendere la struttura e il contenuto del repository indesialto. Si esegue un'analisi della lista dei file, che include:

• Artefatti JSON;
• GML (Graph Modelling Language);
• GraphML (XML-based Graph Representation).

Un'altra funzione interessante è la capacità di caricare file grafici e utilizzarli per generare PageRank o rilevare gruppi di moduli attraverso algoritmi di community detection.

Analisi Git e documentazione

Repowise permette di visualizzare lo stato del repository Git e ottenere informazioni sulle modifiche. La componente documentale è particolarmente utile se l'ambiente è alimentato da un modello LLM (come Anthropic o OpenAI). In quel caso si potranno effettuare query specifiche per trovare moduli o informazioni specifiche, come "How does Signer detect tampered payloads?" oppure "URL-safe token signing?".

Rilevatore codice morto

Una componente chiave di Repowise è il rilevamento di codice morto, che aiuta a mantenere il progetto snello e manutenibile. Viene eseguito utilizzando il comando repowise dead-code o repowise dead-code --safe-only. I moduli che rientrano nella soglia definita (0.7) vengono segnalati come "safe to delete" e quindi candidati per rimozione.

Decisioni architetturali

Può essere utile inserire decisioni architetturali direttamente nel codice, come commenti inline, ad esempio in signer.py. Queste possono spiegare le design choices, le motivazioni tecniche, o le scelte prese per aumentare la stabilità e la scalabilità. Dopo aver eseguito repowise update, queste decisioni saranno rilevabili attraverso query specifiche e analisi del contesto. Vengono anche visualizzate statistiche sulla salute delle decisioni architetturali tramite repowise decision health.

Creazione del file CLAUDE.md

Repowise genera un file di contesto denominato CLAUDE.md, con un'anteprima che contiene informazioni essenziali per il modello LLM di comprensione. Questo file rappresenta quasi sempre il punto di partenza per generare interazioni intelligenti con Repowise.

Strumenti simili a MCP tramite CLI

Repowise offre diverse API di controllo a riga di comando che funzionano simili ai comandi getdeadcode, search_codebase e query per il modello di intelligenza artificiale. Ad esempio:

• repowise dead-code --safe-only;
• repowise search "keyword o frase";
• repowise query "What is risky...";
• repowise query "Why are signers stateless";
• repowise query "Explain signer module";
• repowise query "Produce diagram";
• repowise generate-claude-md.

Tutti questi comandi sono eseguiti in riga di comando, rendendo facile integrarli in workflow automatizzati o in strumenti di sviluppo esistenti.

Questa serie di funzioni rende Repowise uno strumento estremamente versatile per gli architetti di software, i responsabili di repository e gli sviluppatori che devono mantenere il codice sotto controllo con informazioni contestuali e modelli automatici.