608 lines
16 KiB
Markdown
608 lines
16 KiB
Markdown
---
|
|
allowed-tools:
|
|
- Read
|
|
- Write
|
|
- Edit
|
|
- Bash
|
|
- Glob
|
|
- Grep
|
|
argument-hint: "[--check] [--full] [--smart] [--service <name>] [--format md|html|json|pdf]"
|
|
description: "Smart incremental updates con cache e multiple export formats per struttura gerarchica V2.0"
|
|
---
|
|
|
|
# Toduba Update Docs V2.0 - Smart Incremental Updates 🔄
|
|
|
|
## Obiettivo
|
|
|
|
Aggiornamento intelligente e incrementale della documentazione gerarchica V2.0 (docs/global, docs/services/, docs/operations/) con cache, change detection avanzata e supporto per multiple export formats.
|
|
|
|
## Argomenti
|
|
|
|
- `--check`: Mostra cosa verrebbe aggiornato senza modificare
|
|
- `--full`: Forza rigenerazione completa (equivalente a toduba-init --force)
|
|
- `--smart`: Abilita cache e ottimizzazioni AI (default: on)
|
|
- `--service <name>`: Aggiorna solo documentazione per il servizio specificato
|
|
- `--format`: Formato export (md, html, json, pdf) - default: md
|
|
|
|
Argomenti ricevuti: $ARGUMENTS
|
|
|
|
## Nuova Struttura Supportata (V2.0)
|
|
|
|
```
|
|
docs/
|
|
├── .toduba-meta/ # Metadata e tracking
|
|
│ ├── project-type.json
|
|
│ ├── services.json
|
|
│ ├── last-update.json
|
|
│ └── service_*.json
|
|
│
|
|
├── global/ # Documentazione globale
|
|
│ ├── README.md
|
|
│ ├── ARCHITECTURE.md
|
|
│ ├── SETUP.md
|
|
│ ├── CONTRIBUTING.md
|
|
│ └── adr/
|
|
│
|
|
├── services/ # Per-service documentation
|
|
│ └── [service-name]/
|
|
│ ├── README.md
|
|
│ ├── SETUP.md
|
|
│ ├── ARCHITECTURE.md
|
|
│ ├── TECH-STACK.md
|
|
│ ├── STYLE-GUIDE.md
|
|
│ ├── ENDPOINTS.md (condizionale)
|
|
│ ├── DATABASE.md (condizionale)
|
|
│ ├── TESTING.md
|
|
│ └── TROUBLESHOOTING.md
|
|
│
|
|
└── operations/ # DevOps docs
|
|
├── DEPLOYMENT.md
|
|
├── CI-CD.md
|
|
├── MONITORING.md
|
|
├── SECURITY.md
|
|
└── ENVIRONMENT-VARS.md
|
|
```
|
|
|
|
## Pre-requisiti
|
|
|
|
```bash
|
|
# Verifica che docs/ esista
|
|
if [ ! -d "docs" ]; then
|
|
echo "❌ Errore: Documentazione non trovata!"
|
|
echo " Esegui prima: /toduba-system:toduba-init"
|
|
exit 1
|
|
fi
|
|
|
|
# Verifica nuova struttura V2.0
|
|
if [ ! -d "docs/.toduba-meta" ]; then
|
|
echo "⚠️ Struttura documentazione V1.0 rilevata!"
|
|
echo " Aggiorna alla V2.0 con: /toduba-system:toduba-init --force"
|
|
echo " (La vecchia documentazione verrà backuppata automaticamente)"
|
|
exit 1
|
|
fi
|
|
|
|
# Verifica metadata essenziali
|
|
if [ ! -f "docs/.toduba-meta/last-update.json" ]; then
|
|
echo "⚠️ Metadata mancante - rigenerazione completa necessaria"
|
|
echo " Esegui: /toduba-system:toduba-init --force"
|
|
exit 1
|
|
fi
|
|
```
|
|
|
|
## Processo di Aggiornamento Intelligente V2.0
|
|
|
|
### Fase 1: Analisi Cambiamenti (Struttura Gerarchica)
|
|
|
|
#### 1.1 Lettura Stato Precedente
|
|
|
|
```bash
|
|
# Leggi metadata V2.0
|
|
LAST_COMMIT=$(cat docs/.toduba-meta/last-update.json | grep -o '"git_commit": *"[^"]*"' | cut -d'"' -f4)
|
|
LAST_UPDATE=$(cat docs/.toduba-meta/last-update.json | grep -o '"timestamp": *"[^"]*"' | cut -d'"' -f4)
|
|
PROJECT_TYPE=$(cat docs/.toduba-meta/project-type.json | grep -o '"type": *"[^"]*"' | cut -d'"' -f4)
|
|
|
|
# Leggi lista servizi
|
|
SERVICES_LIST=$(cat docs/.toduba-meta/services.json | grep -o '"name": *"[^"]*"' | cut -d'"' -f4)
|
|
|
|
echo "📊 Stato precedente:"
|
|
echo " • Ultimo aggiornamento: $LAST_UPDATE"
|
|
echo " • Ultimo commit: ${LAST_COMMIT:0:7}"
|
|
echo " • Tipo progetto: $PROJECT_TYPE"
|
|
echo " • Servizi: $(echo "$SERVICES_LIST" | wc -l)"
|
|
```
|
|
|
|
#### 1.2 Calcolo Differenze
|
|
|
|
```bash
|
|
# Commits dal'ultimo update
|
|
COMMITS_COUNT=$(git rev-list --count ${LAST_COMMIT}..HEAD)
|
|
|
|
# File modificati raggruppati per categoria
|
|
git diff --name-only ${LAST_COMMIT}..HEAD | while read file; do
|
|
case "$file" in
|
|
*/api/* | */routes/* | */controllers/*)
|
|
echo "API: $file" >> changes_api.txt
|
|
;;
|
|
*/components/* | */pages/* | */views/*)
|
|
echo "FRONTEND: $file" >> changes_frontend.txt
|
|
;;
|
|
*/models/* | */schemas/* | */migrations/*)
|
|
echo "DATABASE: $file" >> changes_db.txt
|
|
;;
|
|
*.test.* | *.spec.* | */tests/*)
|
|
echo "TESTS: $file" >> changes_tests.txt
|
|
;;
|
|
esac
|
|
done
|
|
```
|
|
|
|
### Fase 2: Decisione Aggiornamento (Struttura Gerarchica V2.0)
|
|
|
|
#### Matrice di Update per Struttura V2.0:
|
|
|
|
```
|
|
Cambiamenti rilevati → Documenti da aggiornare
|
|
────────────────────────────────────────────────────────
|
|
GLOBAL SCOPE:
|
|
- Root files changes → docs/global/README.md
|
|
- Architecture changes → docs/global/ARCHITECTURE.md
|
|
- Contributing changes → docs/global/CONTRIBUTING.md
|
|
- Setup changes (monorepo) → docs/global/SETUP.md
|
|
|
|
SERVICE SCOPE (per ogni servizio modificato):
|
|
- Source code changes → docs/services/[name]/ARCHITECTURE.md
|
|
- API/Routes changes → docs/services/[name]/ENDPOINTS.md
|
|
- Database/models changes → docs/services/[name]/DATABASE.md
|
|
- Dependencies changes → docs/services/[name]/TECH-STACK.md
|
|
- Test changes → docs/services/[name]/TESTING.md
|
|
- Style/conventions → docs/services/[name]/STYLE-GUIDE.md
|
|
- Any service changes → docs/services/[name]/README.md
|
|
|
|
OPERATIONS SCOPE:
|
|
- CI/CD config changes → docs/operations/CI-CD.md
|
|
- Deployment scripts → docs/operations/DEPLOYMENT.md
|
|
- Monitoring config → docs/operations/MONITORING.md
|
|
- Security policies → docs/operations/SECURITY.md
|
|
- Env vars changes → docs/operations/ENVIRONMENT-VARS.md
|
|
|
|
METADATA (always):
|
|
- docs/.toduba-meta/last-update.json
|
|
- docs/.toduba-meta/service_*.json (se servizio modificato)
|
|
```
|
|
|
|
#### Rilevamento Servizio da File Modificato
|
|
|
|
```bash
|
|
detect_affected_service() {
|
|
local file_path="$1"
|
|
|
|
# Leggi servizi e i loro path
|
|
while IFS= read -r service_name; do
|
|
service_path=$(cat "docs/.toduba-meta/service_${service_name}.json" | grep -o '"path": *"[^"]*"' | cut -d'"' -f4)
|
|
|
|
# Se il file è nel path del servizio
|
|
if [[ "$file_path" == "$service_path"* ]]; then
|
|
echo "$service_name"
|
|
return
|
|
fi
|
|
done <<< "$SERVICES_LIST"
|
|
|
|
# Se non trovato, è probabilmente global
|
|
echo "global"
|
|
}
|
|
```
|
|
|
|
#### Soglie per Update:
|
|
|
|
- **Minor** (< 5 file): Aggiorna solo file specifici
|
|
- **Medium** (5-20 file): Aggiorna categoria + INDEX
|
|
- **Major** (> 20 file): Considera update completo
|
|
- **Structural** (nuove cartelle/moduli): ARCHITECTURE.md obbligatorio
|
|
|
|
### Fase 3: Update Incrementale
|
|
|
|
#### 3.1 Per API_ENDPOINTS.md:
|
|
|
|
```javascript
|
|
// Analizza solo endpoint modificati
|
|
const modifiedControllers = getModifiedFiles("controllers");
|
|
const modifiedRoutes = getModifiedFiles("routes");
|
|
|
|
// Estrai endpoint esistenti
|
|
const existingEndpoints = parseExistingEndpoints("API_ENDPOINTS.md");
|
|
|
|
// Analizza nuovi/modificati
|
|
const updatedEndpoints = analyzeEndpoints(modifiedControllers, modifiedRoutes);
|
|
|
|
// Merge intelligente
|
|
const mergedEndpoints = mergeEndpoints(existingEndpoints, updatedEndpoints);
|
|
|
|
// Rigenera solo sezioni cambiate
|
|
updateSections("API_ENDPOINTS.md", mergedEndpoints);
|
|
```
|
|
|
|
#### 3.2 Per COMPONENTS.md:
|
|
|
|
```javascript
|
|
// Simile approccio per componenti UI
|
|
const modifiedComponents = getModifiedFiles(["components", "pages"]);
|
|
|
|
// Aggiorna solo componenti modificati
|
|
for (const component of modifiedComponents) {
|
|
const componentDoc = generateComponentDoc(component);
|
|
replaceSection("COMPONENTS.md", component.name, componentDoc);
|
|
}
|
|
```
|
|
|
|
#### 3.3 Per DATABASE_SCHEMA.md:
|
|
|
|
```javascript
|
|
// Rileva modifiche schema
|
|
const schemaChanges = detectSchemaChanges();
|
|
|
|
if (schemaChanges.migrations) {
|
|
appendSection(
|
|
"DATABASE_SCHEMA.md",
|
|
"## Migrazioni Recenti",
|
|
schemaChanges.migrations
|
|
);
|
|
}
|
|
|
|
if (schemaChanges.newModels) {
|
|
updateModelsSection("DATABASE_SCHEMA.md", schemaChanges.newModels);
|
|
}
|
|
```
|
|
|
|
### Fase 4: Smart Merge Strategy
|
|
|
|
#### Preservazione Contenuto Custom:
|
|
|
|
```markdown
|
|
<!-- TODUBA:START:AUTO -->
|
|
|
|
[Contenuto generato automaticamente]
|
|
|
|
<!-- TODUBA:END:AUTO -->
|
|
|
|
<!-- TODUBA:CUSTOM:START -->
|
|
|
|
[Contenuto custom preservato durante update]
|
|
|
|
<!-- TODUBA:CUSTOM:END -->
|
|
```
|
|
|
|
#### Conflict Resolution:
|
|
|
|
1. Preserva sempre sezioni custom
|
|
2. Se conflitto in auto-generated:
|
|
- Backup versione vecchia
|
|
- Genera nuova
|
|
- Marca conflitti per review
|
|
|
|
### Fase 5: Validazione e Report
|
|
|
|
#### Se `--check`:
|
|
|
|
```
|
|
🔍 Toduba Update Docs - Analisi Cambiamenti
|
|
|
|
📊 Sommario:
|
|
- Commits dall'ultimo update: 15
|
|
- File modificati: 23
|
|
- Categorie impattate: API, Frontend, Tests
|
|
|
|
📝 Documenti che verrebbero aggiornati:
|
|
✓ INDEX.md (sempre aggiornato)
|
|
✓ API_ENDPOINTS.md (8 endpoint modificati)
|
|
✓ COMPONENTS.md (3 nuovi componenti)
|
|
✓ TESTING.md (nuovi test aggiunti)
|
|
○ DATABASE_SCHEMA.md (nessun cambiamento)
|
|
○ ARCHITECTURE.md (nessun cambiamento strutturale)
|
|
|
|
⏱️ Tempo stimato: ~8 secondi
|
|
|
|
Esegui senza --check per applicare gli aggiornamenti.
|
|
```
|
|
|
|
#### Update Effettivo:
|
|
|
|
```
|
|
🔄 Toduba Update Docs - Aggiornamento in Corso...
|
|
|
|
[===========----------] 55% Analizzando API changes...
|
|
[==================---] 85% Aggiornando COMPONENTS.md...
|
|
[====================] 100% Completato!
|
|
|
|
✅ Documentazione Aggiornata con Successo!
|
|
|
|
📊 Riepilogo Update:
|
|
- File analizzati: 23
|
|
- Documenti aggiornati: 4/10
|
|
- Tempo impiegato: 7.3s
|
|
- Risparmio vs regenerazione: ~45s
|
|
|
|
📝 Modifiche applicate:
|
|
✓ INDEX.md - Statistiche aggiornate
|
|
✓ API_ENDPOINTS.md - 8 endpoint aggiornati, 2 nuovi
|
|
✓ COMPONENTS.md - 3 nuovi componenti documentati
|
|
✓ TESTING.md - Coverage aggiornato al 87%
|
|
|
|
💾 metadata.json aggiornato:
|
|
- last_updated: 2024-10-31T15:30:00Z
|
|
- commits_since_generation: 0
|
|
- git_info.last_commit: abc123def
|
|
|
|
💡 Tip: Usa --check la prossima volta per preview
|
|
```
|
|
|
|
### Fase 6: Auto-Invocazione da Orchestrator
|
|
|
|
Quando chiamato automaticamente:
|
|
|
|
1. Sempre modalità silenziosa (no verbose)
|
|
2. Log minimo solo se errori
|
|
3. Return status code per orchestrator
|
|
4. Se fallisce, non bloccare task principale
|
|
|
|
## Ottimizzazioni Performance
|
|
|
|
1. **Caching**: Cache analisi file per 5 minuti
|
|
2. **Parallel Processing**: Analizza categorie in parallelo
|
|
3. **Incremental Parsing**: Parse solo diff, non file interi
|
|
4. **Smart Skip**: Skip file non documentabili (.test, .spec)
|
|
5. **Batch Updates**: Accumula modifiche, scrivi una volta
|
|
|
|
## Smart Incremental Updates (H1)
|
|
|
|
### Cache System
|
|
|
|
```typescript
|
|
class DocumentationCache {
|
|
private cache = new Map();
|
|
private maxAge = 5 * 60 * 1000; // 5 minuti
|
|
|
|
async getAnalysis(filePath: string): Promise<Analysis | null> {
|
|
const cached = this.cache.get(filePath);
|
|
if (cached && Date.now() - cached.timestamp < this.maxAge) {
|
|
return cached.analysis;
|
|
}
|
|
return null;
|
|
}
|
|
|
|
setAnalysis(filePath: string, analysis: Analysis) {
|
|
this.cache.set(filePath, {
|
|
analysis,
|
|
timestamp: Date.now(),
|
|
hash: this.calculateHash(filePath),
|
|
});
|
|
}
|
|
|
|
async isValid(filePath: string): Promise<boolean> {
|
|
const cached = this.cache.get(filePath);
|
|
if (!cached) return false;
|
|
|
|
const currentHash = await this.calculateHash(filePath);
|
|
return cached.hash === currentHash;
|
|
}
|
|
}
|
|
```
|
|
|
|
### Smart Change Detection
|
|
|
|
```javascript
|
|
// Usa git diff con analisi semantica
|
|
const detectSmartChanges = async () => {
|
|
const changes = {
|
|
breaking: [],
|
|
feature: [],
|
|
bugfix: [],
|
|
refactor: [],
|
|
documentation: [],
|
|
};
|
|
|
|
// Analizza AST per determinare tipo di cambiamento
|
|
const diff = await git.diff("--cached", "--name-status");
|
|
|
|
for (const file of diff) {
|
|
const analysis = await analyzeFileChange(file);
|
|
|
|
// Categorizza in base al contenuto, non solo al path
|
|
if (analysis.breaksAPI) changes.breaking.push(file);
|
|
else if (analysis.addsFeature) changes.feature.push(file);
|
|
else if (analysis.fixesBug) changes.bugfix.push(file);
|
|
else if (analysis.refactors) changes.refactor.push(file);
|
|
else changes.documentation.push(file);
|
|
}
|
|
|
|
return changes;
|
|
};
|
|
```
|
|
|
|
### Dependency Graph Updates
|
|
|
|
```typescript
|
|
// Aggiorna solo documenti dipendenti
|
|
const updateDependentDocs = async (changedFile: string) => {
|
|
const dependencyGraph = await loadDependencyGraph();
|
|
const affected = dependencyGraph.getDependents(changedFile);
|
|
|
|
// Update solo documenti realmente impattati
|
|
for (const doc of affected) {
|
|
await updateSection(doc, changedFile);
|
|
}
|
|
};
|
|
```
|
|
|
|
## Multiple Export Formats (H2)
|
|
|
|
### Format Converters
|
|
|
|
```typescript
|
|
interface FormatConverter {
|
|
convert(markdown: string, options?: any): string | Buffer;
|
|
extension: string;
|
|
mimeType: string;
|
|
}
|
|
|
|
const converters: Record<string, FormatConverter> = {
|
|
html: {
|
|
convert: (md) => {
|
|
const html = marked.parse(md);
|
|
return `
|
|
<!DOCTYPE html>
|
|
<html>
|
|
<head>
|
|
<title>Toduba Documentation</title>
|
|
<link rel="stylesheet" href="toduba-docs.css">
|
|
</head>
|
|
<body>${html}</body>
|
|
</html>`;
|
|
},
|
|
extension: ".html",
|
|
mimeType: "text/html",
|
|
},
|
|
|
|
json: {
|
|
convert: (md) => {
|
|
const sections = parseMarkdownToSections(md);
|
|
return JSON.stringify(
|
|
{
|
|
version: "2.0.0",
|
|
generated: new Date().toISOString(),
|
|
sections,
|
|
metadata: getMetadata(),
|
|
},
|
|
null,
|
|
2
|
|
);
|
|
},
|
|
extension: ".json",
|
|
mimeType: "application/json",
|
|
},
|
|
|
|
pdf: {
|
|
convert: async (md) => {
|
|
// Usa markdown-pdf o puppeteer
|
|
const html = marked.parse(md);
|
|
return await generatePDF(html);
|
|
},
|
|
extension: ".pdf",
|
|
mimeType: "application/pdf",
|
|
},
|
|
};
|
|
```
|
|
|
|
### Export Pipeline
|
|
|
|
```javascript
|
|
const exportDocumentation = async (format: string = "md") => {
|
|
const converter = converters[format];
|
|
if (!converter) throw new Error(`Format ${format} not supported`);
|
|
|
|
// Crea directory per formato
|
|
const outputDir = `docs/export/${format}`;
|
|
await fs.mkdir(outputDir, { recursive: true });
|
|
|
|
// Converti tutti i documenti
|
|
for (const file of await glob("docs/*.md")) {
|
|
const content = await fs.readFile(file, "utf8");
|
|
const converted = await converter.convert(content);
|
|
|
|
const outputName = path.basename(file, ".md") + converter.extension;
|
|
await fs.writeFile(`${outputDir}/${outputName}`, converted);
|
|
}
|
|
|
|
console.log(`✅ Exported to ${outputDir}/`);
|
|
};
|
|
```
|
|
|
|
### Format-Specific Templates
|
|
|
|
```typescript
|
|
// Templates per diversi formati
|
|
const templates = {
|
|
html: {
|
|
css: `
|
|
.toduba-docs {
|
|
font-family: 'Inter', sans-serif;
|
|
max-width: 1200px;
|
|
margin: 0 auto;
|
|
}
|
|
.sidebar { position: fixed; left: 0; width: 250px; }
|
|
.content { margin-left: 270px; }
|
|
.code-block { background: #f4f4f4; padding: 1rem; }
|
|
`,
|
|
},
|
|
|
|
pdf: {
|
|
pageSize: "A4",
|
|
margins: { top: "2cm", bottom: "2cm", left: "2cm", right: "2cm" },
|
|
header: "🤖 Toduba Documentation",
|
|
footer: "Page {page} of {pages}",
|
|
},
|
|
};
|
|
```
|
|
|
|
## Gestione Errori
|
|
|
|
- **Metadata corrotto**: Fallback a rigenerazione
|
|
- **Git history perso**: Usa timestamp per determinare modifiche
|
|
- **Conflitti merge**: Crea .backup e procedi
|
|
- **Docs readonly**: Alert user, skip update
|
|
- **Out of sync**: Se > 100 commits, suggerisci --full
|
|
- **Cache invalido**: Invalida e rigenera
|
|
- **Export fallito**: Mantieni formato originale
|
|
|
|
## Performance Metrics
|
|
|
|
```
|
|
📊 Smart Update Performance:
|
|
- Cache hit rate: 75%
|
|
- Average update time: 3.2s (vs 45s full)
|
|
- Memory usage: -60% con streaming
|
|
- File I/O: -80% con cache
|
|
```
|
|
|
|
## Integrazione con Orchestrator
|
|
|
|
L'orchestrator invoca automaticamente quando:
|
|
|
|
```javascript
|
|
if (modifiedFiles > 10 || majorRefactoring || newModules) {
|
|
await invokeCommand("toduba-update-docs --smart");
|
|
}
|
|
```
|
|
|
|
Non viene invocato per:
|
|
|
|
- Modifiche a singoli file
|
|
- Fix di typo/commenti
|
|
- Modifiche solo a test
|
|
- Operazioni di configurazione
|
|
|
|
## Output con Multiple Formats
|
|
|
|
```
|
|
🔄 Toduba Smart Update - Multiple Formats
|
|
|
|
📊 Analisi Smart:
|
|
- Cache hits: 18/23 (78%)
|
|
- Semantic changes detected: 5
|
|
- Affected documents: 3
|
|
|
|
📝 Generazione formati:
|
|
[====] MD: ✅ 100% (base format)
|
|
[====] HTML: ✅ 100% (con styling)
|
|
[====] JSON: ✅ 100% (structured data)
|
|
[====] PDF: ✅ 100% (print-ready)
|
|
|
|
✅ Export completato:
|
|
- docs/export/html/
|
|
- docs/export/json/
|
|
- docs/export/pdf/
|
|
|
|
⚡ Performance:
|
|
- Tempo totale: 4.8s
|
|
- Risparmio: 89% vs full regeneration
|
|
```
|