From f58a6d1d7034d3cb2c5fde06cd2b62450be3058c Mon Sep 17 00:00:00 2001 From: Till JS Date: Tue, 31 Mar 2026 14:09:14 +0200 Subject: [PATCH] docs: document Ecosystem Health Score in about.md and CLAUDE.md Add comprehensive documentation for the Ecosystem Health Score: - 12 metrics explained with weights and measurement methods - How each score is calculated - How to improve each metric - Script usage: node scripts/ecosystem-audit.mjs Co-Authored-By: Claude Opus 4.6 (1M context) --- CLAUDE.md | 10 ++++ .../landing/src/content/manascore/about.md | 51 +++++++++++++++++++ 2 files changed, 61 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index fcc509a05..75f8adcad 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -887,6 +887,16 @@ Backend, Frontend, Database, Testing, Deployment, Documentation, Security, UX | **Dependency Health** | Outdated packages, vulnerabilities by severity | | **API Conformity** | 7 checks (responses, errors, pagination, versioning, docs, health, validation) | | **Cross-App Consistency** | Shared package usage (auth, ui, theme, branding, i18n, error-tracking) | +| **Analytics Maturity** | 5 checks (page views, custom events, auth tracking, landing, dashboard) | + +### Ecosystem Health Score + +Measures consistency and unification **across all apps** (vs. ManaScore which rates each app individually). + +**Dashboard:** `/manascore/ecosystem` +**Script:** `node scripts/ecosystem-audit.mjs` — scans the monorepo, generates `ecosystem-health.json` + +12 metrics with weighted average: Shared Packages (20%), Icon Consistency (10%), i18n (10%), Styles (10%), Local-First (8%), Error Boundaries (8%), TypeScript Strict (7%), Tests (7%), Modals (5%), Error Handling (5%), PWA (5%), Maintainability (5%). ### Maturity Levels diff --git a/apps/manacore/apps/landing/src/content/manascore/about.md b/apps/manacore/apps/landing/src/content/manascore/about.md index 4dc0f5458..efb1d7613 100644 --- a/apps/manacore/apps/landing/src/content/manascore/about.md +++ b/apps/manacore/apps/landing/src/content/manascore/about.md @@ -237,6 +237,57 @@ Misst wie konsequent eine App die shared Packages des Monorepos nutzt: --- +### Ecosystem Health Score + +Der **Ecosystem Health Score** ist ein eigenständiges Dashboard unter `/manascore/ecosystem`, das die **Konsistenz und Vereinheitlichung über alle Apps hinweg** misst. Während der ManaScore jede App einzeln bewertet, bewertet der Ecosystem Health Score das **Gesamtsystem**. + +**Script:** `node scripts/ecosystem-audit.mjs` — scannt den gesamten Monorepo und generiert `ecosystem-health.json`. + +#### 12 Metriken (gewichteter Durchschnitt = Gesamtscore) + +| Metrik | Gewicht | Was wird gemessen | +| --------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Shared Packages** | 20% | Adoption der 6 Core-Packages (`shared-auth`, `shared-ui`, `shared-theme`, `shared-branding`, `shared-i18n`, `shared-error-tracking`) über alle Apps | +| **Icon Consistency** | 10% | Verhältnis Phosphor-Icon-Imports vs. verbleibende inline SVGs | +| **i18n Coverage** | 10% | Apps mit `svelte-i18n` Internationalisierung | +| **Style Consistency** | 10% | Apps mit Theme-CSS-Variablen + Tailwind CSS | +| **Local-First** | 8% | Apps mit `@manacore/local-store` (Offline-fähig) | +| **Error Boundaries** | 8% | Apps mit `+error.svelte` Error Page + Offline Page | +| **TypeScript Strict** | 7% | Apps mit `strict: true` in tsconfig | +| **Test Coverage** | 7% | Apps mit mindestens einem Unit- oder E2E-Test | +| **Modal Consistency** | 5% | Anteil Modals die `shared-ui Modal` nutzen vs. Custom | +| **Error Handling** | 5% | Shared `getErrorMessage()`/`withErrorHandling()` vs. inline `instanceof Error` | +| **PWA Support** | 5% | Apps mit manifest.json + Service Worker | +| **Maintainability** | 5% | Anteil Dateien unter 500 Zeilen (große Dateien = Refactoring-Bedarf) | + +#### Wie der Score berechnet wird + +``` +Ecosystem Health Score = Σ (Metrik × Gewicht) / Σ Gewichte +``` + +Jede Metrik ist ein Prozentwert (0-100%): + +- **Package-basierte Metriken** (Shared Packages, Local-First, PWA): Anteil der Apps die das Package nutzen +- **Pattern-basierte Metriken** (Icons, Modals, Errors): Verhältnis shared/standard vs. custom/inline +- **Feature-basierte Metriken** (Error Boundaries, Tests, i18n): Anteil der Apps die das Feature haben +- **Code-Quality-Metriken** (Maintainability): Inverse Relation zu großen Dateien + +#### Wie man den Score verbessert + +| Metrik | Aktion | +| ------------------- | ------------------------------------------------------------------------------- | +| Shared Packages ↑ | Fehlende Core-Packages in `package.json` hinzufügen | +| Icon Consistency ↑ | Inline SVGs durch `@manacore/shared-icons` Phosphor-Komponenten ersetzen | +| Modal Consistency ↑ | Custom-Modals auf `` aus `@manacore/shared-ui` migrieren | +| Error Handling ↑ | `instanceof Error` durch shared `getErrorMessage()` Helper ersetzen | +| Error Boundaries ↑ | `+error.svelte` in jeder App anlegen | +| Test Coverage ↑ | Mindestens einen Unit-Test pro App schreiben | +| PWA Support ↑ | `manifest.json` + `service-worker.ts` hinzufügen | +| Maintainability ↑ | Dateien >500 Zeilen refactoren (Composables extrahieren, Komponenten aufteilen) | + +--- + ## Reifegradstufen | Stufe | Score | Bedeutung |