Ulas
1122bd269b
Replace all — with - in all source files (JS, CSS, HTML, JSON, Markdown) for consistency and readability. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
12 KiB
12 KiB
Repository Hygiene Audit - Oikos
Datum: 2026-04-02
Version: 0.5.2 (Tag v0.5.2)
Branch: main (Commit 922c0b7)
Phase 1: Dead Files & Orphans
1.1 Verwaiste Dateien
| # | Datei | Status | Begründung | Empfehlung |
|---|---|---|---|---|
| 1 | .worktrees/feature/ |
Verwaist | Leeres Verzeichnis - Überrest eines abgeschlossenen Git-Worktree. Kein Inhalt. | Löschen (rm -rf .worktrees/feature/) |
Keine verwaisten JS/CSS/HTML-Dateien gefunden. Alle Module in public/pages/, public/components/, public/styles/ und server/routes/ sind korrekt referenziert:
- Alle CSS-Dateien in
public/styles/sind inpublic/index.htmlverlinkt - Alle Page-Module werden vom Router geladen
- Alle Web Components (
oikos-install-prompt,oikos-locale-picker) sind referenziert rrule-ui.jswird voncalendar.jsundtasks.jsimportiertpublic/utils/ux.jswird von 7 Page-Modulen importiertpublic/offline.htmlist im Service Worker als Offline-Fallback referenziertlucide.min.jswird inindex.htmlgeladensw-register.jswird inindex.htmlgeladen
1.2 Superseded / Veraltete Dateien
| # | Datei | Status | Begründung | Empfehlung |
|---|---|---|---|---|
| - | - | - | Keine gefunden. | - |
Keine .bak, .old, .tmp-Dateien vorhanden. Sauber.
1.3 Dev Artifacts
| # | Datei | Status | Begründung | Empfehlung |
|---|---|---|---|---|
| 1 | .env |
OK | Existiert lokal, nicht von Git getrackt, in .gitignore gelistet. |
Kein Handlungsbedarf |
| 2 | .claude/ |
OK | In .gitignore, nicht getrackt. |
Kein Handlungsbedarf |
| 3 | .worktrees/ |
OK | In .gitignore, nicht getrackt. Leeres feature/-Verzeichnis (s. 1.1). |
Leeres Subdir löschen |
| 4 | docs/superpowers/ |
OK | In .gitignore, nicht getrackt. Enthält 7 Plandokumente (3076 Zeilen) lokal. |
Kein Handlungsbedarf - .gitignore greift |
1.4 Prompt-Dateien
Keine prompt-*.md Dateien im Repository gefunden. Die docs/superpowers/-Pläne und Specs sind Claude-Code-interne Artefakte, korrekt über .gitignore ausgeschlossen.
1.5 Leere oder Stub-Dateien
| # | Datei | Status | Begründung | Empfehlung |
|---|---|---|---|---|
| - | - | - | Keine leeren oder Stub-Dateien gefunden. | - |
1.6 Sonderfall: Hilfs-/Script-Dateien
| # | Datei | Zeilen | Genutzt von | Empfehlung |
|---|---|---|---|---|
| 1 | server/db-schema-test.js |
185 | Allen 7 Test-Dateien (test-*.js) |
Behalten - aktiv genutzte Test-Infrastruktur |
| 2 | scripts/seed-demo.js |
343 | Manuell (CLI-Script für Screenshots) | Behalten - nützliches Dev-Tool |
| 3 | test-browser-loader.mjs |
- | package.json test:modal-utils |
Behalten - aktiv genutzt für Browser-API-Mocks |
Phase 2: Vollständigkeit der Projektdateien
2.1 Muss vorhanden sein
| Datei | Status | Bewertung |
|---|---|---|
.gitignore |
✅ Vorhanden & vollständig | 47 Zeilen. Deckt ab: node_modules, .env, SQLite DBs (*.db, *.db-shm, *.db-wal), Logs, OS-Dateien (.DS_Store, Thumbs.db), Build-Artefakte (dist/, .cache/, coverage/), Docker-Volume (data/), IDE (.vscode/, .idea/, *.swp), .claude/, .worktrees/, docs/superpowers/, *.txt (mit robots.txt Ausnahme). Sicherheitsnetz für Token-Dateien via *.txt-Glob. CLAUDE.md ist ebenfalls in .gitignore und nicht mehr getrackt (korrekt). |
LICENSE |
✅ Vorhanden & korrekt | MIT License, Copyright 2026 ulsklyc. |
README.md |
✅ Vorhanden & umfassend | Siehe Phase 2b für Detailaudit. |
CONTRIBUTING.md |
✅ Vorhanden & vollständig | 252 Zeilen. Hard Constraints, Dev Setup, Projekt-Struktur, Workflow (6 Schritte), Conventional Commits mit Oikos-Scopes dokumentiert (tasks, shopping, meals, calendar, budget, notes, contacts, auth, db, ui, pwa), Code Conventions (General/Frontend/Backend/Testing), Changelog-Guide, Issue/PR-Anleitung, Security-Verweis. |
SECURITY.md |
✅ Vorhanden & vollständig | Vulnerability Reporting via GitHub Private Advisories, Scope-Definition, Security-Features-Übersicht, Supported-Versions-Policy. |
CHANGELOG.md |
⚠️ Vorhanden, kleiner Fehler | Keep a Changelog Format, retroaktive Versionierung ab 0.1.0 ✅. Problem: Compare-Links am Dateiende: [Unreleased] verweist auf v0.5.1...HEAD statt v0.5.2...HEAD. Außerdem fehlt der [0.5.2]-Compare-Link. |
CLAUDE.md |
✅ Vorhanden & aktuell | Behavioral guide (109 Zeilen), nicht von Git getrackt (in .gitignore). Beschreibt Architektur, Konventionen, Security, DB, Deployment, Implementation Status. Keine Duplikation von SPEC.md. |
BACKLOG.md |
✅ Vorhanden & aktuell | Enthält erledigte Features als Referenztabelle (BL-01 bis BL-10 mit Versionszuordnung). Aktiv keine offenen Einträge - korrekt für aktuellen Projektstand. |
docs/SPEC.md |
✅ Vorhanden | Nicht im Detail geprüft (Umfang), aber von CLAUDE.md und README.md referenziert und zentral für alle Module. |
.dockerignore |
⚠️ Vorhanden, kleiner Fehler | Sinnvolle Ausschlüsse. Problem: Referenziert docs/social-preview.html - diese Datei existiert nicht (nur docs/social-preview.png existiert). Harmlos (Ausschluss einer nicht-existenten Datei), aber irreführend. |
docker-compose.yml |
✅ Vorhanden | Nicht im Detail geprüft, aber vorhanden und funktional laut README/CHANGELOG. |
Dockerfile |
✅ Vorhanden | Nicht im Detail geprüft, vorhanden. |
.github/ISSUE_TEMPLATE/bug_report.md |
✅ Vorhanden & vollständig | Gutes Template mit Description, Steps to Reproduce, Expected/Actual Behavior, Environment, Logs (collapsible), Additional Context. |
.github/ISSUE_TEMPLATE/feature_request.md |
✅ Vorhanden & vollständig | Problem/Solution/Alternatives-Struktur, Scope-Checkboxen pro Modul, Constraints-Check (vanilla JS, no build step, no frontend deps). |
.github/PULL_REQUEST_TEMPLATE.md |
✅ Vorhanden & vollständig | Summary, Changes, Checklist (tests, conventions, no deps, i18n, changelog). |
2.2 Sollte vorhanden sein
| Datei | Status | Bewertung |
|---|---|---|
docs/ Verzeichnis |
✅ Vorhanden | Enthält SPEC.md, logo.svg, social-preview.png, Screenshots (4 Varianten × 9 Module = 36 Screenshots). |
manifest.json |
✅ Vorhanden | public/manifest.json - PWA-Manifest. |
| Service Worker | ✅ Vorhanden | public/sw.js + public/sw-register.js. |
.nvmrc |
✅ Vorhanden | Inhalt: 22. Konsistent mit engines.node: ">=22.0.0" in package.json. |
.env.example |
✅ Vorhanden & vollständig | 39 Zeilen. Alle dokumentierten Env-Vars abgedeckt: PORT, NODE_ENV, SESSION_SECRET, SESSION_SECURE, DB_PATH, DB_ENCRYPTION_KEY, OpenWeather, Google Calendar, Apple CalDAV, Sync-Intervall, Rate-Limiting. |
nginx.conf.example |
✅ Vorhanden | Referenziert in README. |
.github/workflows/ci.yml |
✅ Vorhanden & sinnvoll | Matrix: Node 22.x + 24.x, permissions: contents: read (Least Privilege), actions/checkout@v4, npm ci, npm test. |
2.3 Sonstiges
| Element | Status | Bewertung |
|---|---|---|
| Git Tags | ✅ Konsistent | v0.1.0 bis v0.5.2 - alle CHANGELOG-Versionen haben entsprechende Tags. |
scripts/ |
✅ Sinnvoll | generate-icons.js (Dev-Tool) und seed-demo.js (Screenshot-Generierung). Beide in .dockerignore exkludiert. |
entrypoint.sh |
✅ Vorhanden | Docker-Entrypoint. |
setup.js |
✅ Vorhanden | Admin-Setup-Wizard, in README dokumentiert. |
Phase 2b: README-Audit
| Kriterium | Status | Bewertung |
|---|---|---|
| Projektname und Kurzbeschreibung | ✅ Vorhanden | Logo + "Oikos" + "The self-hosted family planner that respects your privacy." - klar und prägnant. |
| Badges | ✅ Vorhanden | 7 Badges: Release, License, Node.js, Docker, SQLCipher, PWA, i18n. flat-square Style. |
| Screenshots/Demo | ✅ Vorhanden & hervorragend | 9 Mobile-Screens (dark/light auto-switch via <picture>), 8 Tablet-Screens in collapsible Section. Alle 4 Varianten (mobile-dark, mobile-light, tablet-dark, tablet-light). |
| Features-Übersicht | ✅ Vorhanden | 8 Module in 2-Spalten-Tabelle + "And also"-Absatz mit Querschnittsfunktionen. |
| Tech Stack | ✅ Vorhanden | Badges + Detailtabelle (Server, Database, Frontend, Auth, Deployment, Integrations). |
| Voraussetzungen | ✅ Vorhanden | Docker + Docker Compose. Node.js-Version im Badge und Development-Section. |
| Installation/Setup | ✅ Vorhanden | 5-Schritt Quick Start (clone, configure, start, setup admin, open). Klar und Copy-Paste-fähig. |
| Konfiguration (.env) | ✅ Vorhanden | Collapsible "Configuration" Section mit Required/Optional/Weather/Integrations Tabellen. Verweis auf .env.example. |
| Nutzung (erster Login) | ✅ Vorhanden | Admin-Account-Erstellung, Family Members via Settings erklärt. |
| Architektur-Überblick | ✅ Vorhanden | In collapsible "Development" Section mit Verzeichnisbaum und Request-Flow-Beschreibung. |
| API-Dokumentation | ✅ Vorhanden | Eigene "API" Section mit Verweis auf docs/SPEC.md und server/routes/. |
| Contributing-Verweis | ✅ Vorhanden | Link auf CONTRIBUTING.md. |
| Security-Verweis | ✅ Vorhanden | Eigene "Security" Section mit Feature-Tabelle. |
| License-Verweis | ✅ Vorhanden | "MIT © 2026 ulsklyc" mit Link. |
| Roadmap / BACKLOG-Verweis | ✅ Vorhanden | Eigene "Roadmap" Section mit Link auf BACKLOG.md und Feature-Request-Issue-Template. |
| Backup & Restore | ✅ Vorhanden | Collapsible Section mit Docker-Volume Backup/Restore-Befehlen. |
| Updates | ✅ Vorhanden | Collapsible Section mit git pull && docker compose up -d --build. |
| Calendar Sync Setup | ✅ Vorhanden | Collapsible Section mit Google + Apple Setup-Anleitungen. |
Gesamtbewertung README: Vollständig und professionell. Keine fehlenden Sektionen. Gute Nutzung von collapsible Sections für Detailtiefe ohne die Hauptseite zu überladen.
Phase 3: Priorisierte Aufgabenliste
[P2] CHANGELOG.md Compare-Links korrigieren
- Was: Die Referenz-Links am Ende von CHANGELOG.md sind inkonsistent:
[Unreleased]verweist aufv0.5.1...HEAD→ solltev0.5.2...HEADsein[0.5.2]-Link fehlt komplett →v0.5.1...v0.5.2ergänzen
- Warum: GitHub-Links in der gerenderten CHANGELOG zeigen falschen Diff für Unreleased-Änderungen. Besucher sehen v0.5.2-Änderungen im Unreleased-Diff statt nur echte Unreleased-Änderungen.
- Aufwand: 5 Minuten
- Dateien:
CHANGELOG.md(Zeilen 139–147)
[P2] .dockerignore - Phantomreferenz entfernen
- Was:
.dockerignoreexkludiertdocs/social-preview.html, aber diese Datei existiert nicht (nurdocs/social-preview.pngexistiert). - Warum: Irreführend bei Code-Review oder Wartung. Kein funktionaler Impact.
- Aufwand: 5 Minuten
- Dateien:
.dockerignore(Zeile mitdocs/social-preview.html)
[P3] Leeres Worktree-Verzeichnis aufräumen
- Was:
.worktrees/feature/ist ein leeres Verzeichnis, Überrest eines abgeschlossenen Git-Worktree. - Warum: Kein funktionaler Impact (in .gitignore), aber unnötiger Eintrag im lokalen Dateisystem.
- Aufwand: 1 Minute
- Dateien:
.worktrees/feature/
Zusammenfassung
| Kategorie | Ergebnis |
|---|---|
| Verwaiste Dateien | 1 Fund (leeres Worktree-Dir) - P3 |
| Superseded Files | 0 Funde |
| Dev Artifacts | Korrekt durch .gitignore abgedeckt |
| Prompt-Dateien | Keine im Repo |
| Leere Dateien | 0 Funde |
| Projektdateien | 2 Minor-Issues (CHANGELOG-Links, .dockerignore Phantom) - P2 |
| README | Vollständig, keine Lücken |
| P0-Findings | 0 |
| P1-Findings | 0 |
| P2-Findings | 2 |
| P3-Findings | 1 |
Gesamtbewertung: Das Repository ist in sehr gutem Zustand. Alle essenziellen Projektdateien sind vorhanden und inhaltlich vollständig. Die .gitignore ist gut durchdacht. Die README ist professionell und deckt alle relevanten Aspekte ab. Die drei gefundenen Issues sind Minor/Kosmetik-Korrekturen ohne funktionalen Impact.