Cerca codice con il grafo del codice

Questa guida mostra come portare un repo nel grafo del codice e poi usarlo per rispondere alla domanda che ti poni davvero prima di un refactoring: cosa dipende da questo?

Il grafo del codice è un database di simboli e archi costruito analizzando i checkout registrati con tree-sitter. I suoi strumenti sono rivolti agli agenti: li raggiungi chiedendo a un agente.

Prima di iniziare

Il grafo indicizza Dart, JavaScript, TypeScript, TSX, PHP, Python, Rust, Zig, C, C++, Go, Java, Ruby, C#, Swift, Kotlin, R, Assembly, MATLAB e Ada. I file in qualsiasi altra lingua non vengono analizzati, quindi non compaiono in search_code, code_symbol, code_callers, code_callees o code_impact.

Altri due fattori determinano cosa viene indicizzato:

In un worktree git, l’enumerazione si affida a git ls-files --cached --others --exclude-standard, quindi ogni .gitignore, i file di ignore annidati, .git/info/exclude e il file di esclusione globale vengono rispettati. È questo che tiene node_modules e i risultati delle build fuori dal grafo.
Il Dart generato viene scartato comunque. I file generati di solito sono versionati, quindi git da solo non li escluderebbe, e cambiano a ogni esecuzione della generazione di codice.

Indicizza un repo

Registrare un checkout attiva RepoAdded, che avvia automaticamente per esso la pipeline index_code. Vedi Aggiungi repo a uno spazio di lavoro.

Per reindicizzare a mano:

Apri Impostazioni → Spazio di lavoro → Repository.
Fai clic sul pulsante Indicizza codice nella riga del repo.
Mentre è in esecuzione, il pulsante mostra i file completati sul totale, con un comando di annullamento. Al termine si stabilizza in una spunta con il conteggio dei simboli.

Il grafo è partizionato per spazio di lavoro, repo e checkout: il checkout collegato è una partizione, e ogni worktree di spazio ha la propria (con chiave sul suo id di repo isolato).

Vale la pena conoscere due limitatori, perché spiegano un’attesa che sembra un blocco:

Il watcher dei file ammette una sola esecuzione di indicizzazione alla volta sull’host — un secondo checkout aspetta. La pipeline index_code è limitata separatamente a un’esecuzione per spazio di lavoro, quindi due repo nello stesso spazio di lavoro si accodano; spazi di lavoro diversi possono indicizzare in parallelo. L’indicizzatore stesso serializza due esecuzioni dello stesso checkout, così l’avvio di una pipeline e una scansione del watcher non possono analizzarlo due volte.
I worktree appartenenti a spazi dormienti (nessun messaggio nell’ultima settimana) non vengono né osservati né indicizzati. I checkout collegati restano osservati. Una decisione di salto viene ricontrollata dopo cinque minuti, quindi uno spazio che torna attivo viene ripreso.

Trova un simbolo

Chiedi a un agente di cercare. Lo strumento è search_code e richiede sia uno spazio di lavoro sia un repo:

search_code(workspace_id: "...", repo_id: "...", query: "authentication middleware")

Gli id dei repo provengono da list_repos. L’argomento opzionale mode è keyword, semantic o hybrid e il valore predefinito è hybrid — BM25 su nomi, firme e commenti di documentazione, fuso con la similarità vettoriale.

Ogni risultato porta l’id, il nome, il nome qualificato, il tipo, il percorso del file, la riga di inizio e quella di fine del simbolo e la sua firma, quando ne ha una. L’id è l’handle che passi a ogni altro strumento di questa pagina.

Quando conosci il nome esatto, cercalo direttamente:

code_symbol(workspace_id: "...", repo_id: "...", name: "MyClass")

Traccia le chiamate

Entrambi richiedono uno symbol_id da un risultato di ricerca, più un limit opzionale (predefinito 50):

code_callers(workspace_id: "...", symbol_id: "...")
code_callees(workspace_id: "...", symbol_id: "...")

code_callers restituisce i simboli con un arco in entrata verso questo; code_callees restituisce quelli da cui dipende.

Verifica cosa romperebbe una modifica

Questo è lo strumento per cui esiste l’intera pagina:

code_impact(workspace_id: "...", symbol_id: "...", depth: 3)

Calcola il raggio delle dipendenze inverse: tutto ciò che dipende, direttamente o transitivamente, dal simbolo lungo gli archi calls, extends e implements (gli import, i mix-in e i riferimenti generici sono archiviati nel grafo ma non vengono percorsi qui). depth è il numero massimo di salti, tra 1 e 6, con valore predefinito 2.

Il risultato è composto da tre campi:

root — il simbolo su cui hai chiesto informazioni
impacted — l’insieme raggiungibile, che include la radice a profondità 0, ciascuno con il proprio depth dalla radice
edgeCount — quanti archi ha attraversato la traversata, come conteggio invece che come archi stessi

Eseguilo prima di rinominare o modificare una firma e passa all’agente l’elenco degli elementi coinvolti come suo ambito.

I risultati vengono verificati sulla copia di lavoro del chiamante

Per un chiamante agente, l’id dello spazio viene iniettato automaticamente e i risultati vengono verificati sulla copia di lavoro di quello spazio. Un simbolo il cui file non esiste più nell’albero del chiamante viene omesso e la risposta porta un conteggio staleOmitted più una nota che dice che l’indice è obsoleto per quei simboli.

È per questo che tu e un agente potete ottenere risposte diverse alla stessa query, e che un agente in uno spazio può ottenere una risposta diversa da un agente in un altro. Ogni conversazione di uno spazio condivide quell’unico worktree. La verifica fallisce in modo permissivo: si preferisce una risposta obsoleta a una vuota.

Chiedi a un agente di eseguire code_impact (o review_studio.blastRadius) quando vuoi il raggio d’impatto di una modifica. Vedi Calcolo della revisione.

La ricerca semantica richiede il modello di embedding

I simboli e i fatti ricevono un embedding al momento della scrittura, e solo se il modello di embedding sul dispositivo è installato. Fino ad allora, mode: "semantic" e la metà semantica della modalità ibrida non hanno nulla con cui confrontarsi e la ricerca è di fatto solo per parola chiave.

Installa il modello in Impostazioni → Server → Diagnostica e privacy → Ricerca semantica prima di indicizzare. I simboli ricevono un vettore quando il loro file viene acquisito.

Nota anche che qualsiasi ricompilazione del binario del server riprepara le dylib delle grammatiche e ne cambia gli mtime, il che invalida ogni checkpoint dell’indice e forza una nuova scansione completa di ogni checkout all’esecuzione successiva. Ricalcola gli hash, ma non ri-estrae i file invariati.

Cosa c’è nel grafo

Tipi di simbolo: function, method, class, field, enum, constructor, getter, setter, typedef, extension, mixin, variable.

Tipi di arco: calls, imports, extends, implements, mixes in, references.

Le firme canoniche di questi strumenti si trovano in Strumenti MCP.

Guide correlate

Concetti correlati

Spazi di lavoro e isolamento