Track HiveGrid Cloud planning reference

This commit is contained in:
david committed 2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
5784 files changed
+1104929 -3

No files matched your search

@@ -0,0 +1,288 @@
# Bundle-Budgets per-Route mit PR-Comment-Visualisierung
**Status:** completed
**Task-ID:** #71
**Phase:** 10
**Estimated Effort:** 3-4 Tage Initial-Setup
**Owner:** unassigned
## Problem
`scripts/verify-bundle-size.mjs` enforced ein globales Bundle-Limit, aber:
- **Keine per-Route-Limits**: Dashboard-Route schleicht still über 500 KB ohne jemanden zu alarmieren; KB-Article-Route kann mit 50 KB auskommen, aber Limit ist als „Mittelwert" konfiguriert
- **Hartes Fail bei Überschreitung**: Build bricht, PR steckt — kein gradueller Warning-Pfad
- **Keine Visualisierung**: Reviewer sehen die tatsächlichen Per-Route-Bundle-Sizes nicht im PR; Debugging „warum ist Bundle gewachsen?" erfordert lokales Tooling
- **Keine Trend-Analyse**: Bundle-Growth über die Zeit unsichtbar — Audit-Findings „Bundle ist in den letzten 3 Monaten um 40 % gewachsen" werden zu spät bemerkt
- **Manual-Bundle-Visualizer fehlt**: Entwickler haben kein einfaches Tool um lokale Bundle-Composition zu inspizieren
Betroffene Codestellen:
- `scripts/verify-bundle-size.mjs` — bestehende Script
- `scripts/verify-bundle-size.test.mjs` — bestehende Tests
- `apps/web/vite.config.ts` — Build-Config
- `.github/workflows/ci.yml` + `.gitea/workflows/ci.yml` — CI-Integration
## Depends on
- `01-tech-debt-foundation/dep-updates.md` — Vite + rollup-plugin-visualizer aktuell
- Empfehlenswert (nicht hart): `10-compliance-polish/lighthouse.md` — manualChunks-Splitting wird dort etabliert, hier wird die Budget-Verifikation darauf angewendet
## Blocks
Keine harten Blocks.
## Approach
**Vier koordinierte Sub-Komponenten:**
### (a) Per-Route-Bundle-Limits in `scripts/verify-bundle-size.mjs`
Config-File `scripts/bundle-budgets.json`:
```json
{
"default": { "limitKb": 200, "warningKb": 180 },
"routes": {
"app/$tenant/dashboard": { "limitKb": 250, "warningKb": 225 },
"app/$tenant/crm": { "limitKb": 250, "warningKb": 225 },
"app/$tenant/crm/contacts": { "limitKb": 200, "warningKb": 180 },
"app/$tenant/settings/members": { "limitKb": 220, "warningKb": 200 },
"app/$tenant/settings/billing": { "limitKb": 220, "warningKb": 200 },
"app/$tenant/email-marketing": { "limitKb": 280, "warningKb": 250 },
"kb/$slug": { "limitKb": 150, "warningKb": 135 },
"auth/login": { "limitKb": 100, "warningKb": 90 },
"auth/register": { "limitKb": 100, "warningKb": 90 },
"auth/magic-link": { "limitKb": 80, "warningKb": 75 },
"admin/dashboard": { "limitKb": 220, "warningKb": 200 },
"admin/analytics": { "limitKb": 300, "warningKb": 275 },
"/": { "limitKb": 180, "warningKb": 160 }
},
"vendorChunks": {
"vendor-misc": { "limitKb": 300, "warningKb": 280 },
"vendor-recharts": { "limitKb": 200, "warningKb": 180 },
"vendor-react-email": { "limitKb": 150, "warningKb": 135 }
}
}
```
Sizes gemessen in **gzip-bytes** (nicht raw — gzip ist transport-relevant).
Script-Logik:
- Iteriere über alle gebauten Route-Files (`dist/client/assets/route-*.js`)
- Map Route-File-Name → Route-Pattern aus React-Router-v7-Manifest
- Wende Per-Route-Limit aus Config an; fallback zu Default
- Bei Warning-Überschreitung: yellow Output, kein Build-Bruch
- Bei Limit-Überschreitung: red Output, **Warning (nicht Fail)** in CI — PR-Comment statt Block
- Vendor-Chunks separat behandelt mit eigenem Limit-Set
### (b) PR-Comment-Output
CI-Job postet PR-Comment mit Markdown-Tabelle:
```
| Route | Size (gzip) | Limit | Status | Δ from main |
|---|---|---|---|---|
| app/$tenant/dashboard | 248 KB | 250 KB | ✅ | +12 KB |
| app/$tenant/crm | 261 KB | 250 KB | ⚠️ exceeds | +4 KB |
| auth/login | 87 KB | 100 KB | ✅ | -3 KB |
| vendor-recharts | 195 KB | 200 KB | ✅ | 0 KB |
```
- Mit `actions/github-script` oder Gitea-equivalent
- Comment wird upsert: Update statt Append (sucht existing Comment via Marker `<!-- bundle-budget-report -->`)
- Bei `main`-Vergleich: lade letztes `main`-Build-Manifest (CI-Artifact) und vergleiche
### (c) Vite-Bundle-Visualizer als Dev-Command
`packages.json` Script `bundle:visualize`:
```json
"bundle:visualize": "vite build --mode analyze && open dist/stats.html"
```
`apps/web/vite.config.ts`:
```ts
plugins: [
// ...
...(process.env.NODE_ENV === 'analyze' ? [
visualizer({ filename: 'dist/stats.html', open: false, gzipSize: true, brotliSize: true })
] : [])
]
```
`rollup-plugin-visualizer` als Dev-Dep.
Entwickler-Workflow: `pnpm bundle:visualize` → öffnet Treemap im Browser → identifiziert große Module → optimiert.
### (d) Vite-Config-Tweaks für besseres Splitting
Koordiniert mit `lighthouse.md` Step 4:
```ts
build: {
rollupOptions: {
output: {
manualChunks(id) {
if (id.includes('node_modules')) {
if (id.includes('lodash')) return 'vendor-lodash';
if (id.includes('date-fns')) return 'vendor-date-fns';
if (id.includes('recharts')) return 'vendor-recharts';
if (id.includes('@sentry')) return 'vendor-sentry';
if (id.includes('@react-email')) return 'vendor-react-email';
if (id.includes('react-pdf') || id.includes('pdfkit')) return 'vendor-pdf';
return 'vendor-misc';
}
}
}
},
chunkSizeWarningLimit: 200, // KB raw — Vite-internal warning, ergänzt unsere Budget-Checks
}
```
Dynamic-Imports für nicht-kritische Module (siehe `lighthouse.md` Step 4).
### (e) Dokumentation
- `docs/performance/bundle-budgets.md`:
- Wie Bundle-Budgets funktionieren
- Wie Per-Route-Limits konfiguriert werden
- Wie PR-Comment-Output gelesen wird
- Lokaler Visualizer-Workflow
- Anti-Patterns (Don't lazy-load critical-path, Don't bundle-split shared deps)
- Bewusste Exceptions (welche Routes haben höhere Limits und warum)
**Warum nicht Alternativen:**
- ❌ **Hartes Fail bei Überschreitung**: blockiert PRs für legitime Feature-Adds; Warning-Comment-Approach ist Sichtbarkeits-getrieben statt Block-getrieben
- ❌ **Globales Limit**: Routes haben unterschiedliche Komplexität — globales Limit ist immer falsch (zu lax für Auth, zu strict für Dashboard)
- ❌ **Webpack-Bundle-Analyzer**: Vite-Bundle-Visualizer (`rollup-plugin-visualizer`) ist Vite-native
- ❌ **Size-Limit Library**: gut für simple Cases, aber keine Per-Route-Logik out-of-the-box; Custom-Script ist flexibler
## Implementation Steps
1. **`bundle-budgets.json` Config-File**
- Files: `scripts/bundle-budgets.json`, `scripts/bundle-budgets.schema.json` (JSON-Schema für Validation)
- Initial-Werte aus aktuellem Build-Snapshot ableiten (current sizes + 10 % Headroom)
- Commit: `10-compliance-polish/bundle-budget: add per-route budget config`
2. **`verify-bundle-size.mjs` erweitern**
- Files: `scripts/verify-bundle-size.mjs`, `scripts/verify-bundle-size.test.mjs`
- Per-Route-Limit-Lookup, gzip-Size-Berechnung, Warning vs Fail-Behavior
- React-Router-v7-Manifest-Parsing für Route-File-Mapping
- Tests: Per-Route-Limit-Match, Default-Fallback, Vendor-Chunk-Limit, Warning vs Error
- Commit: `10-compliance-polish/bundle-budget: extend verify script with per-route limits`
3. **Vite-Config-manualChunks + Visualizer-Plugin**
- Files: `apps/web/vite.config.ts`, `apps/web/package.json`
- manualChunks pro Vendor-Library; visualizer-Plugin nur im `analyze`-Mode
- `bundle:visualize`-Script
- Commit: `10-compliance-polish/bundle-budget: split vendor chunks and add bundle visualizer`
4. **CI-PR-Comment-Action (GitHub)**
- Files: `.github/workflows/bundle-budget.yml`
- Job läuft nach `build`-Job, lädt vorheriges `main`-Manifest, postet PR-Comment via `actions/github-script`
- Marker `<!-- bundle-budget-report -->` für Upsert
- Commit: `10-compliance-polish/bundle-budget: add github workflow with pr comment`
5. **CI-PR-Comment-Action (Gitea)**
- Files: `.gitea/workflows/bundle-budget.yml`
- Gitea-API-Call statt `actions/github-script`; Comment-Upsert via Marker
- Commit: `10-compliance-polish/bundle-budget: add gitea workflow with pr comment`
6. **Main-Build-Manifest-Artifact-Persistence**
- Files: `.github/workflows/main-bundle-baseline.yml`, `.gitea/workflows/main-bundle-baseline.yml`
- Auf `main`-Push: Bundle-Manifest als Artifact uploaden mit Tag `main-baseline-<sha>`
- PR-Workflow lädt das letzte Artifact für Δ-Vergleich
- Commit: `10-compliance-polish/bundle-budget: persist main bundle baseline as ci artifact`
7. **Dokumentation**
- Files: `docs/performance/bundle-budgets.md`
- Workflow-Beschreibung, Config-Format, PR-Comment-Output-Erklärung, Visualizer-Anleitung
- Commit: `10-compliance-polish/bundle-budget: document bundle budget workflow`
## Test Requirements
- **Unit-Tests** (`verify-bundle-size.test.mjs`):
- Per-Route-Limit-Lookup: Route gefunden → korrektes Limit
- Default-Fallback: Route nicht in Config → default-Limit
- Vendor-Chunk-Match: Vendor-Chunk-Name → vendor-Limit
- Gzip-Size-Berechnung: bekannter Input → erwartete Size
- Warning-Behavior: Size im Warning-Range → yellow Output, exit code 0
- Error-Behavior: Size > Limit → red Output, **exit code 0** (kein Block, nur Warning), aber Report-Flag setzen
- **Integration-Test:**
- End-to-End: `pnpm build && node scripts/verify-bundle-size.mjs` → korrekter Output für aktuelles Build
- **CI-Workflow-Test:** Test-PR pushen → PR-Comment erscheint mit Bundle-Tabelle; zweiter Push → Comment wird upsert (nicht dupliziert)
- **Bundle-Visualizer-Test:** `NODE_ENV=analyze pnpm build` → `dist/stats.html` existiert und ist valide HTML
- **Coverage-Target:** ≥ 90 % im `verify-bundle-size.mjs` (kritischer Quality-Gate-Code)
- **Test-Files:** `scripts/verify-bundle-size.test.mjs` (extended)
**NICHT als completed markieren bevor PR-Comment auf einem Test-PR erscheint und korrekte Sizes anzeigt.**
## Acceptance Criteria
- [ ] `scripts/bundle-budgets.json` enthält Per-Route-Limits für mind. 12 Routes + Vendor-Chunks
- [ ] `verify-bundle-size.mjs` erweitert um Per-Route-Logik; Tests grün
- [ ] Vite-manualChunks splittet Vendor-Bundles
- [ ] `pnpm bundle:visualize` öffnet Treemap im Browser
- [ ] GitHub-Workflow postet PR-Comment mit Bundle-Tabelle + Δ-Vergleich gegen main
- [ ] Gitea-Workflow ebenso
- [ ] Main-Bundle-Baseline wird als CI-Artifact persistiert
- [ ] Warning-Mode: bei Überschreitung kein PR-Block, aber sichtbarer Comment
- [ ] Coverage ≥ 90 % in `verify-bundle-size.mjs`
- [ ] `pnpm lint`, `pnpm typecheck`, `pnpm test` grün
- [ ] `docs/performance/bundle-budgets.md` angelegt
- [ ] Detail-MD Progress Log aktualisiert
- [ ] PROGRESS.md Status auf `completed`
## Rollback Strategy
- **Bundle-Budgets zu strict**: Limits in `bundle-budgets.json` lockern via Commit; kein Code-Rollback nötig
- **PR-Comment-Workflow brokens PR-Flow**: Workflow-File auf `if: false` setzen via Commit → Comment-Posting deaktiviert
- **manualChunks-Config bricht App**: Vite-Config-Commit reverten; default-Splitting funktioniert
- **Visualizer-Plugin erhöht Build-Time** zu stark: `analyze`-Mode-Gate entfernt visualizer aus Default-Build → keine Auswirkung
- **CI-Artifact-Storage voll**: Artifact-Retention-Policy (7 Tage) konfigurieren
## Security Notes
- **Bundle-Budgets enthalten keine Secrets**: Config ist Public-Code
- **PR-Comment-Token**: GitHub-Token braucht `pull-requests: write`-Scope (minimal); Gitea-Equivalent
- **Bundle-Visualizer-Output (`stats.html`)**: enthält Source-Maps-Referenzen → niemals als Public-Artifact deployen, nur lokal/Artifact-Storage
- **Main-Bundle-Baseline-Artifact**: enthält Datei-Namen und Sizes, keine Source-Maps → unbedenklich
## Subagent Recommendations
- **Planning:** `Plan`-Subagent mit dieser Detail-MD + existierendem `verify-bundle-size.mjs` als Input — soll Per-Route-Config-Schema validieren
- **Research:** `Explore`-Subagent mit Auftrag „lauf `pnpm build` lokal und liste Sizes pro Route-File aus `dist/client/assets/`; schlage Initial-Limits vor (current + 10 %)"
- **Implementation:** Ein `general-purpose`-Subagent pro Implementation-Step (1-7), parallel-fähig (außer 4/5 die nach 1-3 sequenziell)
- **Tests:** Test-Code direkt mit Implementation in Step 2 + Workflow-Tests in Step 4/5
- **Verification:** `gsd-verifier` für Acceptance-Criteria; PR-Comment-Verifikation auf Test-PR
- **Code-Review:** `gsd-code-reviewer` nach Step 7, Fokus auf Script-Robustness (Edge-Cases bei manualChunks-Renames, Manifest-Parsing-Fehler)
## Staging-Deployment-Steps
Dieser Task hat keine Staging-Komponenten — alles läuft in CI gegen Build-Artifacts. Aber:
1. Branch `agent/10-bundle-budget` pushen
2. PR öffnen → GitHub-Workflow läuft → PR-Comment erscheint mit Bundle-Tabelle
3. **Visualisierung-Verifikation lokal**: `pnpm bundle:visualize` → Treemap zeigt Vendor-Chunks-Split korrekt
4. **Main-Baseline-Verifikation**: nach Merge zu `main` → Workflow lädt Manifest als Artifact → nächster PR zeigt Δ-Vergleich
5. **Warning-Test**: künstlich großen Import in einen Route-File einbauen → PR-Comment zeigt Warning-Status für diese Route
## Deviations from Plan
- **No separate `manualChunks` change.** The Vite config already implements vendor-chunk splitting via `apps/web/app/utils/build/manualChunks.ts` (vendor-react, vendor-charts, vendor-ai-sdk, vendor-editor-tiptap, vendor-editor-prosemirror, vendor-markdown, vendor-monaco, vendor-pdf, vendor-workflow, vendor-core-utils). Implementation Step (d) of the spec was a no-op — the budgets reference those existing chunk names.
- **Baseline download in Gitea is opt-in via `BUNDLE_BASELINE_URL`.** Gitea Actions artifact-download isn't a first-class action in this repo's runner image, so the workflow uses a curl-fetched URL if the operator configures one and otherwise renders the PR comment with Δ-from-main as `—`. GitHub uses `dawidd6/action-download-artifact` for the same purpose.
- **`chunkSizeWarningLimit` left at 1800.** The spec suggested tightening to 200 KB, but the existing config intentionally keeps Rollup quiet so our own gates control the noise. Lowering would surface raw-byte warnings for chunks that are already within our gzip budgets.
## Progress Log
- 2026-05-17 16:38 — `a0e2c1c9` — add bundle-budgets json config with per-route limits (15 routes + 12 vendor chunks)
- 2026-05-17 16:43 — `b618eea2` — extend verify-bundle-size with per-route enforcement (gzip-size + status taxonomy + --json / --per-route-only flags; 30 unit tests pass)
- 2026-05-17 16:45 — `8d2050e7` — integrate rollup-plugin-visualizer as ANALYZE_BUNDLE=true opt-in; preserves Sentry + asset-CDN base
- 2026-05-17 16:46 — `7fbfcab4` — add GitHub + Gitea PR-comment workflows, baseline workflow, renderer + Gitea upserter; 12 renderer tests pass
- 2026-05-17 16:47 — `c4374eb8` — add `docs/architecture/bundle-budgets.md`
## Lessons Learned
- React Router v7 build emits both client and server passes via a single `pnpm build`; the visualizer plugin's default `closeBundle` hook fires once per pass. For multi-pass builds, prefer `emitFile: false` + an absolute `filename` so the treemap lands deterministically in `apps/web/build/`.
- The existing group-budget gate in `verify-bundle-size.mjs` already covers regressions in initial-payload size. The per-route budget layer is purely visibility/communication — non-blocking is the right default.