Questo capitolo è una guida visiva alle due viste a grafo di AITM: il Contract Explorer (una mappa di tutti i Behavioral Contracts di un progetto) e App Flow (una mappa di come un singolo elemento dell'applicazione è collegato a tutto il resto). Spiega che cosa mostra ciascun grafo, come leggere nodi, colori e linee di collegamento, che cosa significa la legenda e a che cosa servono realmente entrambe le viste.

Contract Explorer & App Flow

Chi non conosce ancora il significato di Contract o di knowledge graph, può leggere prima Contracts, Knowledge Graph & Hints. Questo capitolo ne costituisce il seguito e si concentra esclusivamente sulla navigazione delle due visualizzazioni.

Contract Explorer — la mappa dei Contract del progetto

A cosa serve: il Contract Explorer è un grafo interattivo di tutti i Behavioral Contracts di un progetto, cioè i fatti memorizzati su come si comporta ogni parte del codice. In un'unica schermata si vede quanta conoscenza AITM possiede sul progetto, quanto è coperta dai test, quali moduli sono i più grandi e come i Contract si collegano a file, variabili e documentazione. È il modo più rapido per rispondere alla domanda "che cosa sa AITM del mio progetto?" — e per individuare i punti deboli (Contract non testati o in errore).

Dove si trova: nel pannello del progetto, fare clic sulla sotto-tab Contracts (le sotto-tab del progetto sono Develop, Testing, Archive, Setting, Optimize, Contracts, Graph e Multi Graph). La sotto-tab adiacente Graph disegna il grafo del codice del progetto, mentre Multi Graph lo disegna per tutti i progetti della tab insieme (viene mostrata solo quando la tab contiene più di un progetto).

Che cosa c'è sullo schermo

La schermata si compone di quattro aree principali:

• Barra superiore — tab dei dataset, statistiche di riepilogo e pulsanti di azione.
• Barra laterale sinistra — ricerca, filtri per modulo ed elenco dei Contract.
• Area principale del grafo — il grafo interattivo (zoom con la rotellina del mouse, spostamento trascinando, i nodi possono essere trascinati).
• Legenda (pannello in sovrimpressione in basso a sinistra del grafo) — spiega i colori dei nodi e i tipi di linea.

Barra superiore — tab e statistiche

Livelli di visualizzazione — Module View e All Contracts

Sopra il grafo si trova un selettore del livello di dettaglio:

• Module View (predefinita per i progetti di grandi dimensioni, oltre 500 Contract) — ogni nodo è un intero modulo (ad es. "AI Chat", "Backup Service"). La dimensione della bolla riflette il numero di Contract nel modulo; le linee tra moduli indicano che condividono file sorgente. È la "vista dall'alto", il punto di partenza ideale.
• Facendo clic su un modulo si passa al Module Detail — il grafo mostra i singoli Contract del modulo selezionato.
• All Contracts — il grafo completo di tutti i Contract in una volta sola. Nei progetti di grandi dimensioni è limitato a 500 nodi per ragioni di prestazioni (un badge mostra il conteggio, con un link "Show all" per aggirare deliberatamente il limite).

Nell'angolo in alto a destra del grafo si trova inoltre un selettore del renderer: SVG, Sigma (predefinito — WebGL, gestisce grafi di grandi dimensioni), 3D, Cosmo e deck.gl. Non cambia le funzionalità, ma solo il modo in cui il grafo viene disegnato: se il grafo risulta a scatti su un progetto grande, scegliere Sigma.

Leggere il grafo — i nodi

Ogni nodo (cerchio) rappresenta un'entità. Il colore indica il tipo e, per i Contract, indica contemporaneamente anche lo stato dei test:

Nodo più grande = entità più significativa (un modulo con più Contract, un Contract con danger zone, ecc.).

Leggere il grafo — le linee (relazioni)

Le linee tra i nodi significano "queste due cose sono collegate". Il tipo di relazione è codificato nello stile della linea:

Lettura pratica: le linee continue = relazioni nel codice, le linee tratteggiate = relazioni attraverso la documentazione. Una linea tratteggiata che parte da un Contract significa che per esso esiste documentazione scritta — facendo clic sul nodo arancione la si apre direttamente nell'applicazione.

Legenda

La legenda (pannello in basso a sinistra del grafo) riassume esattamente quanto descritto sopra — colori dei nodi e tipi di collegamento. Per i tre stati dei Contract mostra inoltre conteggi e percentuali in tempo reale (ad es. Tested (passing) 4/2403 (0%)): quanti Contract dell'insieme attualmente visualizzato si trovano in ciascuno stato. I numeri vengono ricalcolati in base al filtro attivo — nella Module View si riferiscono ai moduli presenti sullo schermo, dopo l'ingresso in un modulo ai suoi Contract.

Barra laterale sinistra

• Search — ricerca full-text tra ID dei Contract, descrizioni del comportamento, file e variabili.
• Filters / Groups — alterna tra il filtro per modulo (pulsanti con i nomi dei moduli; All rimuove il filtro) e un albero raggruppato.
• Elenco dei Contract (in basso) — si popola con i Contract del modulo selezionato. Ogni riga ha un punto colorato con la stessa semantica dei nodi del grafo (verde/rosso/ambra), più un'icona per i Contract in una danger zone (punti in cui una piccola modifica ha storicamente causato danni sproporzionati).

Dettaglio del Contract

Facendo clic su un Contract (nel grafo o nell'elenco) si apre la finestra di dettaglio del Contract:

In cima al dettaglio si trovano due pulsanti importanti:

• Assembled doc — apre il documento completo assemblato per il Contract.
• Flow — salta direttamente alla vista App Flow (vedere sotto) centrata sulla prima variabile del Contract. È il ponte tra le due visualizzazioni: da "che cosa vale" (il Contract) a "come si inserisce nell'applicazione" (il flusso).

App Flow — la mappa delle relazioni di un elemento

A cosa serve: mentre il Contract Explorer mostra il progetto dall'alto, App Flow risponde alla domanda "come si relaziona questo specifico elemento con il resto dell'applicazione?". Si vedono tutte le variabili del linguaggio di comunicazione adiacenti all'elemento — tramite il suo namespace, tramite Contract condivisi, tramite file condivisi e tramite la navigazione dell'interfaccia. È lo strumento ideale per stimare l'impatto di una modifica ("se tocco questo, che cos'altro viene coinvolto?") e per scrivere prompt di Task precisi.

Dove si trova:

1. Dal Dev Panel — nell'applicazione in esecuzione, fare clic su un elemento; si apre la sua finestra di dettaglio con le tab Graph | Guide & Flow | App Flow.
2. Dal Contract Explorer — tramite il pulsante Flow nel dettaglio del Contract (vedere sopra).

Che cosa c'è sullo schermo

• Colonna sinistra — i dati dell'elemento ispezionato: nome, descrizione, livello e soprattutto l'elenco dei Contract che lo governano (con ID, stato dei test, salute, file e punteggio). Sono le stesse informazioni del Contract Explorer, ma dal punto di vista di un singolo elemento.
• Al centro — il grafo — un grafo interattivo con l'elemento ispezionato al centro e le variabili correlate intorno.
• Pannello destro — i filtri per tipo di relazione (caselle di controllo) e l'elenco delle variabili correlate, che riflette il grafo sotto forma di elenco leggibile.

Leggere il grafo — i nodi

Leggere il grafo — colori degli archi (tipi di relazione)

Ogni linea è colorata in base al motivo per cui le variabili sono collegate:

Pannello destro — filtri ed elenco

In alto si trovano quattro caselle di controllo — Namespace, Contract, File, Navigation — che filtrano sia il grafo sia l'elenco. Per impostazione predefinita sono selezionate Namespace + Contract (le relazioni più utili e meno rumorose); File e Navigation si attivano quando occorre seguire i collegamenti attraverso il codice o attraverso il flusso dell'interfaccia.

Ogni riga dell'elenco mostra il codice della variabile, il nome e i badge del tipo di relazione. Il pulsante (insert into prompt) fissa il codice della variabile direttamente nel prompt del Task in fase di scrittura — il flusso di lavoro tipico è dunque: trovare l'elemento nell'applicazione → ispezionarne l'App Flow → fissare le variabili correlate → descrivere la modifica. L'Agent AI riceve così gli indirizzi esatti dei punti interessati dalla modifica e non deve cercarli.

Legenda e guida

In basso a sinistra del grafo si trova la legenda che riassume gli stili dei nodi e i colori degli archi (esattamente come descritto sopra). In alto a destra c'è il pulsante (?) che apre un popover di aiuto con la spiegazione di che cosa mostra App Flow e di come viene derivato ciascun tipo di relazione:

Guide & Flow — il flusso di business logic

Accanto ad App Flow, il dettaglio dell'elemento dispone di una tab Guide & Flow. Spiega l'elemento selezionato dall'alto verso il basso in passaggi semplici — l'elemento UI stesso e poi i Contract di business che ne descrivono il comportamento (ciascuno con le variabili che riguarda) — e il pulsante Copy as Markdown copia l'intera spiegazione negli appunti, pronta da incollare in un prompt di Task.

AITM Dev Panel

Che cos'è: una piccola barra degli strumenti flottante che AITM può iniettare nell'applicazione web di un progetto che gestisce. Mentre si usa l'applicazione nel browser, il pannello funge da occhi di AITM al suo interno: registra gli elementi UI marcati che vede (costruendo la mappa di schermate, pulsanti e finestre di dialogo del progetto da cui attingono il Contract Explorer e App Flow) e cattura gli errori JavaScript dalla console del browser inviandoli ad AITM, dove compaiono per il progetto e possono essere trasformati in Task di bug.

Come viene aggiunto: il pannello è un unico script servito dal server AITM e incluso nella pagina dell'applicazione in modalità di sviluppo. Il Wizard per i nuovi progetti lo aggiunge automaticamente ai progetti web che crea; anche il Dashboard di AITM stesso lo contiene.

Che cosa si vede: quattro tab —

• Elements — gli elementi su cui si è fatto clic o che sono stati fissati, ciascuno con il proprio codice variabile, i Contract e i file che lo sostengono e gli avvisi dei Contract con danger zone. Overlay evidenzia tutti gli elementi marcati nella pagina; Pin / One Pin raccolgono gli elementi per un prompt; le icone su ogni riga copiano il codice, aprono il dettaglio dell'elemento (Graph, Guide & Flow, App Flow) e rimuovono il pin. Clear Pins svuota l'elenco.
• Records — gli elementi UI che il pannello ha registrato dalla pagina.
• Errors — errori JavaScript e di console catturati in questo browser, con il conteggio nel nome della tab.
• Settings — le opzioni del pannello stesso.

Il pannello compare solo in modalità di sviluppo ed è destinato agli sviluppatori e agli Agent AI, non agli utenti finali dell'applicazione. La sua documentazione completa si apre dal menu dell'intestazione: Help → AITM Dev Panel. Le dimensioni dei caratteri del pannello sono regolabili in Settings → Font & Style.

Flussi di lavoro pratici

Individuare i punti deboli di un modulo: Contracts → Module View → fare clic su un modulo → cercare nel grafo i nodi ambra (non testati) e rossi (in errore). La legenda fornisce le percentuali a colpo d'occhio.

Stimare l'impatto di una modifica prima di creare un Task: trovare l'elemento nell'applicazione tramite il Dev Panel (oppure un Contract nel Contract Explorer e il pulsante Flow) → App Flow → attivare le relazioni contract e file → tutto ciò che è collegato può essere interessato dalla modifica.

Scrivere un prompt preciso: in App Flow, fissare le variabili rilevanti nel prompt — il Task parla così un linguaggio comprensibile sia a chi lo scrive sia agli Agent AI della Pipeline (il linguaggio di comunicazione).

Verificare se un comportamento è documentato: nel Contract Explorer, seguire le linee tratteggiate a partire da un Contract — conducono ai documenti (nodi arancioni) che si aprono con un clic direttamente nell'applicazione.