davideandClaude Sonnet 5.5
ce2db25b4c
Gli avvisi di salute riguardano l'estrazione prima dell'unione, non il graph.json; styles.css manca perché graphify non ha un estrattore CSS. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
93 lines
5.0 KiB
Markdown
93 lines
5.0 KiB
Markdown
# Grafo della conoscenza (graphify)
|
|
|
|
Mappa interrogabile del repository: codice, migrazioni SQL e documentazione, con le relazioni
|
|
tra simboli, file e concetti. Serve a orientarsi in fretta («cosa chiama questa funzione?»,
|
|
«quale decisione tocca questa tabella?»). **Non è fonte di verità**: se grafo e codice
|
|
divergono, vale il codice.
|
|
|
|
## Cosa c'è e dove
|
|
|
|
Il grafo vive in `graphify-out/`, **locale e non versionato** (è in `.gitignore`): si rigenera,
|
|
non si committa. Contiene `graph.json` (dati), `graph.html` (visualizzazione, si apre nel
|
|
browser) e `GRAPH_REPORT.md` (nodi centrali, community, domande suggerite).
|
|
|
|
| Parte | Come è costruita | Costo |
|
|
| ---------------- | ----------------------------------------------- | --------------------- |
|
|
| Codice e SQL | Analisi dell'AST, senza LLM | Gratis, secondi |
|
|
| Documentazione | Estrazione semantica con agenti (`docs/`, ...) | Token, qualche minuto |
|
|
| Immagini e icone | Escluse di proposito: non dicono nulla di utile | Non estratte |
|
|
|
|
## Installazione
|
|
|
|
Una tantum, per ogni sviluppatore. L'extra `[sql]` serve per le migrazioni in
|
|
`supabase/migrations/`: senza, i 53+ file `.sql` non entrano nel grafo.
|
|
|
|
```bash
|
|
uv tool install "graphifyy[sql]"
|
|
```
|
|
|
|
La skill `/graphify` per Claude Code è già nel repo in `.claude/skills/graphify/`.
|
|
Cursor e Codex non la leggono: lì si usa la CLI.
|
|
|
|
## Uso quotidiano
|
|
|
|
```bash
|
|
graphify query "chi scrive in eventi_app?" # domanda in linguaggio naturale
|
|
graphify explain "Squadra" # un nodo e i suoi vicini
|
|
graphify path "GestioneEventi" "eventi_app" # percorso più breve tra due nodi
|
|
```
|
|
|
|
In Claude Code: `/graphify query "..."`, oppure leggere `graphify-out/GRAPH_REPORT.md`.
|
|
|
|
## Quando rigenerarlo
|
|
|
|
| Situazione | Comando | Costo |
|
|
| --------------------------------- | ------------------------------------------------------ | ----------------------------- |
|
|
| Hai cambiato codice o migrazioni | `graphify update .` | Gratis |
|
|
| Hai cambiato documenti in `docs/` | `/graphify . --update` (skill) | Token, solo i file modificati |
|
|
| Grafo assente (clone nuovo) | `graphify update .`, poi la riga sopra per i documenti | Come sopra |
|
|
|
|
Il grafo riporta il commit da cui è stato costruito (`GRAPH_REPORT.md`, sezione «Graph
|
|
Freshness»): confrontalo con `git rev-parse HEAD` per sapere se è vecchio.
|
|
|
|
## Collegamento documenti ↔ codice
|
|
|
|
L'estrazione semantica dei documenti crea pochissimi archi verso il codice, anche quando il
|
|
documento cita il file. Lo script [scripts/graphify-link-docs.ts](../scripts/graphify-link-docs.ts)
|
|
li aggiunge in modo deterministico: per ogni percorso citato nei `.md` (`src/lib/rosa.ts`)
|
|
crea l'arco `references` dal documento al file, e ai simboli citati tra backtick (`useIo`) se
|
|
stanno in quel file. Sono archi EXTRACTED: il percorso è scritto nel testo.
|
|
|
|
```bash
|
|
bun scripts/graphify-link-docs.ts # idempotente, gratis
|
|
```
|
|
|
|
Collega anche i documenti alle RFC che nominano (`RFC 8188/8291`) e unisce i concetti dei
|
|
documenti che hanno lo stesso nome esatto di un simbolo del codice (`mediePagelle()`): questi
|
|
ultimi sono archi `describes` INFERRED, perché si basano solo sul nome.
|
|
|
|
Va rilanciato dopo ogni `/graphify . --update`, perché rielaborare un documento ne cancella
|
|
gli archi. Sopravvive invece a `graphify update .`. Un documento che cita un file solo per nome
|
|
(`rosa.ts`, senza `src/lib/`) non viene collegato: scrivi il percorso completo.
|
|
|
|
Nota: `graphify update .` su un grafo già completo conserva i nodi semantici dei documenti
|
|
(verificato). I `.md` nuovi o modificati entrano però solo come struttura (titoli e sezioni):
|
|
per l'estrazione semantica serve `/graphify . --update`, che rielabora solo quei file.
|
|
|
|
## Limiti noti
|
|
|
|
- Gli avvisi di salute del build («archi su nodi inesistenti», «archi collassati») si
|
|
riferiscono all'estrazione prima dell'unione. Nel `graph.json` finale gli archi su nodi
|
|
inesistenti sono 0; gli archi tra la stessa coppia di nodi con relazioni diverse (import e
|
|
chiamata, o più righe) diventano uno solo e conservano le varianti in `also_seen`. I due
|
|
archi da un nodo a se stesso sono funzioni ricorsive vere. Per ricontrollare:
|
|
`graphify diagnose multigraph`.
|
|
- La coesione bassa di una community non indica da sola un modulo da dividere: nei test, nei
|
|
documenti-indice e nel file generato `routeTree.gen.ts` è normale. Rilette tutte le
|
|
community da 25 nodi in su, nessuna mescola responsabilità diverse nel codice dell'app.
|
|
- Un file letto solo in parte viene riprovato al giro successivo (`--update`).
|
|
- `src/styles.css` non è nel grafo perché graphify non ha un estrattore per il CSS: l'import
|
|
in `__root.tsx` produce solo un nodo segnaposto `src_styles` senza file. I file di
|
|
configurazione (Dockerfile, `.toml`, `.lock`, `.env.example`) restano fuori di proposito:
|
|
`.env.example` non va mai incluso.
|