diff --git a/.gitignore b/.gitignore index abe19a8..4487ed3 100644 --- a/.gitignore +++ b/.gitignore @@ -51,3 +51,6 @@ backups/* !backups/README.md # Automazioni operative locali (backup cifrati, playbook con dati sensibili) ops/ + +# Grafo graphify: locale, si rigenera (docs/GRAFO.md) +graphify-out/ diff --git a/AGENTS.md b/AGENTS.md index b9200f4..2727394 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -18,7 +18,11 @@ usabile dallo smartphone anche da chi non è pratico. [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) vanno lette prima di toccare codice o schema. 2. Verifica lo stato attuale del repository: commit recenti, modifiche non committate, lavoro introdotto da altri collaboratori o da altri assistenti. -3. Non presumere che il progetto sia come l'hai lasciato nell'ultima sessione: la fonte di +3. Se esiste `graphify-out/` (locale, non versionato), usalo per orientarti prima di cercare a + tappeto: `graphify query "..."` e `GRAPH_REPORT.md`. Non è fonte di verità e può essere + vecchio: controlla il commit riportato nel report e, se serve, rigeneralo + (vedi [docs/GRAFO.md](docs/GRAFO.md)). +4. Non presumere che il progetto sia come l'hai lasciato nell'ultima sessione: la fonte di verità è il repository, non la cronologia della conversazione. Non implementare funzionalità non documentate: prima si documenta diff --git a/CLAUDE.md b/CLAUDE.md index bdd4a94..247fb1b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -3,7 +3,8 @@ Le regole di progetto stanno in @AGENTS.md: valgono integralmente e non sono ripetute qui — compresi i comandi (`npm run dev/lint/test`, supabase) e la checklist «Fine lavoro» da eseguire prima di dire che hai finito. La documentazione tecnica è indicizzata in -[docs/README.md](docs/README.md); l'architettura in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md). +[docs/README.md](docs/README.md); l'architettura in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md); +il grafo del repository (graphify) in [docs/GRAFO.md](docs/GRAFO.md). **Non aggiungere regole in questo file.** Una regola nuova va in `AGENTS.md`, che leggono anche Codex e Cursor; scritta qui la vedrebbe solo Claude Code. diff --git a/docs/GRAFO.md b/docs/GRAFO.md new file mode 100644 index 0000000..3455a94 --- /dev/null +++ b/docs/GRAFO.md @@ -0,0 +1,64 @@ +# 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. + +Attenzione: `graphify update .` da solo ricostruisce i `.md` come semplici strutture (titoli e +sezioni) e **sovrascrive** i nodi semantici dei documenti. Dopo averlo lanciato su un grafo +già completo, rilancia `/graphify . --update` per ripristinarli: la cache evita di pagare di +nuovo i file invariati. + +## Limiti noti + +- Il report segnala archi su nodi inesistenti e archi multipli collassati, soprattutto nelle + migrazioni SQL e nei template GitHub: il grafo può essere incompleto in quei punti. +- Un file letto solo in parte viene riprovato al giro successivo (`--update`). +- `src/styles.css` e i file di configurazione (Dockerfile, `.toml`, `.lock`, `.env.example`) + non sono nel grafo. `.env.example` non va mai incluso. diff --git a/docs/README.md b/docs/README.md index 0a500f1..b2fa0fc 100644 --- a/docs/README.md +++ b/docs/README.md @@ -17,6 +17,7 @@ ancora e va **prima documentata** (vedi [DD-002](decisions/DD-002.md)). | [GLOSSARIO.md](GLOSSARIO.md) | Cosa significano i termini del dominio (slot, rosa, convocati, CSI, pagelle…) | | [OPERATIONS.md](OPERATIONS.md) | Ambienti, variabili d'ambiente, migration, rilascio e allestimento di un ambiente nuovo (login Google, primo admin) | | [WORKER_EMAIL.md](WORKER_EMAIL.md) | Come si installa, si gestisce e si diagnostica il worker che invia le notifiche per email | +| [GRAFO.md](GRAFO.md) | Come orientarsi nel codice con il grafo graphify: uso, rigenerazione, limiti | | [CHANGELOG.md](CHANGELOG.md) | Cosa è cambiato e quando | | [archive/](archive/README.md) | Materiale storico non più in uso: non è fonte di verità | | [modules/](modules/) | Specifica funzionale di ogni modulo, una per file |