@noyrax/documentation-system-plugin 1.0.4-beta.2 → 1.0.4-beta.4

package/docs/adr/013-system-functionality-fixes.md

@@ -1,279 +0,0 @@
-# ADR 013: System-Funktionalitäts-Fixes (Generate-Twice, Drift-Validierung, Optionale Felder)
-
-**Status:** Implementiert  
-**Datum:** 2025-10-06  
-**Kontext:** System-Funktionalitäts-Analyse und Fixes (system.plan.md)
-
-## Kontext und Problemstellung
-
-Nach Implementierung der additiven Dokumentations-Generierung (ADR 008-012) wurden drei kritische Probleme identifiziert:
-
-1. **"Generate twice" Problem:** Beim ersten Lauf werden nicht alle Dateien erkannt, es muss zweimal `generate` ausgeführt werden
-2. **Drift-Erkennung nicht sichtbar:** Drift wird erkannt, aber nicht in der Validierungs-UI angezeigt
-3. **Signatur-Validierung zu strikt:** Optionale Felder (`?`) werden als Inkompatibilität erkannt
-
-**Bisheriger Ablauf:**
-1. Beim ersten Lauf: AST-Cache ist leer, aber Git-Filter und komplexe Fallback-Logik führen dazu, dass nicht alle Dateien geparst werden
-2. Drift wird in `generateDocumentationTs` erkannt, aber nur als Warnung angezeigt, nicht in Validierung integriert
-3. Signatur-Validierung vergleicht Signaturen exakt, erkennt aber nicht, dass `symbols: string[]` und `symbols?: string[]` kompatibel sind
-
-**Gewünschter Ablauf:**
-1. Beim ersten Lauf: IMMER Vollscan, keine Git-Filter, alle Dateien parsen
-2. Drift-Erkennung in Validierung integrieren: Drift-Warnungen zu Validierungs-Warnungen hinzufügen, Status auf "gelb" setzen
-3. Signatur-Validierung erkennt optionale Felder als kompatibel
-
-## Entscheidung
-
-### Fix 1: "Generate twice" Problem beheben
-
-**Datei:** `src/extension.ts` (generateDocumentationTs)
-
-**Änderungen:**
-1. **AST-Cache-Check vor Git-Filter:**
-   - Prüfe `isFirstRun` ZUERST
-   - Beim ersten Lauf: IMMER Vollscan, kein Git-Filter
-   - Git-Filter nur bei nachfolgenden Läufen
-
-2. **Parse-Logik vereinfachen:**
-   - Beim ersten Lauf: IMMER parsen (kein AST-Cache-Check)
-   - Bei nachfolgenden Läufen: AST-Cache-Check für unveränderte Dateien
-
-3. **Fallback-Logik entfernen:**
-   - Komplexe Fallbacks (Zeilen 199-268) entfernt
-   - Nur noch Warnung bei Problemen beim ersten Lauf
-
-**Code-Änderungen:**
-```typescript
-// Zeilen 120-150: Vereinfachte Logik
-const isFirstRun = !prevAst || prevAst.entries.length === 0;
-
-// BEIM ERSTEN LAUF: IMMER VOLLSCAN, KEIN GIT-FILTER
-if (isFirstRun) {
-    globalOutput.appendLine(`[cache] Erster Lauf erkannt, verwende Vollscan (${scannedAll.length} Dateien)`);
-    scanned = scannedAll;
-} else if (useGit) {
-    // ... Git-Filter-Logik
-}
-
-// Zeilen 159-194: Parse-Logik
-// BEIM ERSTEN LAUF: IMMER PARSEN
-if (!isFirstRun) {
-    const unchanged = astMap.get(f.repositoryRelativePath) === fileHash;
-    if (unchanged) {
-        // Überspringen
-    }
-}
-```
-
-### Fix 2: Drift-Erkennung in Validierung integrieren
-
-**Datei:** `src/extension.ts` (validateDocumentationTs)
-
-**Änderungen:**
-1. **Drift-Erkennung hinzufügen:**
-   - Signatur-Cache laden
-   - Aktuelle Cache-Entries berechnen
-   - Drift erkennen via `detectDrift()`
-
-2. **Drift-Warnungen integrieren:**
-   - Drift-Warnungen zu Validierungs-Warnungen hinzufügen
-   - Status-Report aktualisieren (Drift erhöht `signatureMismatches`)
-
-3. **UI-Integration:**
-   - Drift-Details werden in Validierungs-UI angezeigt
-   - Status wird auf "gelb" gesetzt, wenn Drift erkannt wird
-
-**Code-Änderungen:**
-```typescript
-// Drift-Erkennung: Signatur-Cache mit aktuellen Symbolen vergleichen
-const currentEntries = computeCacheEntries(allSymbols);
-const drift = detectDrift(prev, currentEntries);
-
-// Drift-Warnungen zu Validierungs-Warnungen hinzufügen
-const driftWarnings: string[] = [];
-if (drift.staleSymbols.length > 0) {
-    driftWarnings.push(`Drift erkannt: ${drift.staleSymbols.length} Symbole mit geänderter Signatur`);
-    drift.staleSymbols.slice(0, 10).forEach(id => {
-        driftWarnings.push(`  - Signatur-Abweichung: ${id}`);
-    });
-}
-
-// Status-Klassifizierung (inkl. Drift)
-const totalSignatureMismatches = signatureMismatches + drift.staleSymbols.length;
-const statusReport = computeValidationStatus(
-    [...mdReport.errors, ...coverage.errors],
-    [...mdReport.warnings, ...driftWarnings],
-    coverage.errors,
-    totalSignatureMismatches,
-    mdReport.errors
-);
-```
-
-### Fix 3: Signatur-Validierung für optionale Felder
-
-**Datei:** `src/validator/signature-matching.ts`
-
-**Änderungen:**
-1. **Formatierung erweitern:**
-   - `formatSignatureForDoc` berücksichtigt jetzt `p.optional` bei Interfaces und Funktionen
-   - Optionale Felder werden als `field?: type` formatiert
-
-2. **Kompatibilitätsprüfung:**
-   - Neue Funktion `isOptionalFieldCompatible()` prüft, ob Signaturen nur durch optionale Felder unterschiedlich sind
-   - `symbols: string[]` und `symbols?: string[]` werden als kompatibel erkannt
-
-**Code-Änderungen:**
-```typescript
-// formatSignatureForDoc: Optionale Felder berücksichtigen
-case 'interface':
-    const props = symbol.signature.parameters.map(p => 
-        `  ${p.name}${p.optional ? '?' : ''}${p.type ? `: ${p.type}` : ''};`
-    ).join('\n');
-
-// Neue Funktion: isOptionalFieldCompatible
-function isOptionalFieldCompatible(expected: string, documented: string): boolean {
-    // Entferne optionale Felder und vergleiche
-    const removeOptional = (s: string) => s.replace(/(\w+)\?(\s*:)/g, '$1$2');
-    const expectedWithoutOptional = removeOptional(expected);
-    const documentedWithoutOptional = removeOptional(documented);
-    
-    if (expectedWithoutOptional === documentedWithoutOptional) {
-        return true; // Nur optionale Felder unterschiedlich → kompatibel
-    }
-    return false;
-}
-
-// In validateSignatureMatching:
-if (expectedSig !== documentedSig && 
-    !isArchitecturallyValid(expectedSig, documentedSig) && 
-    !isOptionalFieldCompatible(expectedSig, documentedSig)) {
-    // Mismatch
-}
-```
-
-## Gelesene Abhängigkeiten aus Dokumentation
-
-**docs/modules/src__extension.ts.md:**
-- `generateDocumentationTs()` - Hauptfunktion für Generierung
-- `validateDocumentationTs()` - Validierungsfunktion
-
-**docs/modules/src__drift__index.ts.md:**
-- `detectDrift(previous, current): DriftResult` - Drift-Erkennung
-- `computeCacheEntries(symbols): CacheEntry[]` - Cache-Entries berechnen
-
-**docs/modules/src__validator__signature-matching.ts.md:**
-- `validateSignatureMatching(symbols, modulesDir): SignatureMismatch[]` - Signatur-Validierung
-- `formatSignatureForDoc(symbol): string` - Signatur-Formatierung
-
-**docs/modules/src__parsers__types.ts.md:**
-- `interface SymbolParameter { optional?: boolean; ... }` - Optionale Felder in Parametern
-
-## Auswirkungen
-
-### Positiv
-- ✅ **"Generate twice" Problem behoben:** Beim ersten Lauf werden jetzt alle Dateien korrekt erkannt
-- ✅ **Drift-Erkennung sichtbar:** Drift wird in Validierungs-UI angezeigt, Status wird auf "gelb" gesetzt
-- ✅ **Signatur-Validierung verbessert:** Optionale Felder werden als kompatibel erkannt
-- ✅ **Vereinfachte Logik:** Komplexe Fallbacks entfernt, Code ist wartbarer
-- ✅ **Besseres Logging:** Klarere Log-Meldungen für Debugging
-
-### Neutral
-- ~50 Zeilen Code geändert in `src/extension.ts`
-- ~30 Zeilen Code geändert in `src/validator/signature-matching.ts`
-- Neue Funktion `isOptionalFieldCompatible()` (~25 Zeilen)
-
-### Trade-offs
-
-- **Vereinfachte Fallback-Logik:**
-  - Komplexe Fallbacks entfernt (könnten in Edge-Cases nützlich sein)
-  - **Mitigation:** Logik oben ist robuster; Fallbacks waren Workaround für fehlerhafte Hauptlogik
-  - **Zukünftige Verbesserung:** Bei Problemen können Fallbacks wieder hinzugefügt werden (mit besserem Logging)
-
-- **Drift-Erkennung in Validierung:**
-  - Drift wird jetzt doppelt erkannt (in generate und validate)
-  - **Mitigation:** Konsistent; beide Stellen nutzen gleiche Cache-Daten
-  - **Zukünftige Verbesserung:** Drift-Erkennung könnte zentralisiert werden
-
-- **Optionale Felder-Kompatibilität:**
-  - Regex-basierte Normalisierung könnte Edge-Cases übersehen
-  - **Mitigation:** Einfache Fälle (nur `?` Unterschied) werden korrekt erkannt
-  - **Zukünftige Verbesserung:** Vollständige TypeScript-Typ-Kompatibilitätsprüfung
-
-## Risiken und Mitigation
-
-- **Risiko:** Beim ersten Lauf werden immer noch nicht alle Dateien erkannt
-  - **Mitigation:** Logik ist vereinfacht und explizit; `isFirstRun` wird ZUERST geprüft
-  - **Test:** Manueller Test: Cache löschen, Generate einmal ausführen, prüfen ob alle Dateien erkannt werden
-
-- **Risiko:** Drift-Erkennung zeigt falsche Ergebnisse
-  - **Mitigation:** Nutzt gleiche Cache-Daten wie in `generateDocumentationTs`
-  - **Test:** Code-Signatur ändern, Generate + Validate ausführen, prüfen ob Drift angezeigt wird
-
-- **Risiko:** Optionale Felder-Kompatibilität erkennt nicht alle Fälle
-  - **Mitigation:** Einfache Regex-Normalisierung für häufige Fälle
-  - **Test:** Interfaces mit optionalen Feldern testen, prüfen ob keine falschen Mismatches erkannt werden
-
-## Design-Entscheidungen
-
-### Alternative 1: Fallback-Logik behalten, aber verbessern
-- **Verworfen:** Fallbacks waren Workaround für fehlerhafte Hauptlogik
-- **Gewählt:** Hauptlogik korrigieren, Fallbacks entfernen
-
-### Alternative 2: Drift-Erkennung nur in generate, nicht in validate
-- **Verworfen:** Drift sollte in Validierung sichtbar sein
-- **Gewählt:** Drift-Erkennung in beide Funktionen integrieren (konsistent)
-
-### Alternative 3: Vollständige TypeScript-Typ-Kompatibilitätsprüfung
-- **Verworfen:** Zu komplex für MVP; würde TypeScript-Compiler erfordern
-- **Gewählt:** Einfache Regex-basierte Normalisierung für häufige Fälle (optionale Felder)
-
-### Alternative 4: Optionale Felder in formatSignatureForDoc ignorieren
-- **Verworfen:** Optionale Felder sind Teil der Signatur und sollten dokumentiert werden
-- **Gewählt:** Optionale Felder formatieren und als kompatibel erkennen
-
-## Nächste Schritte
-
-1. ✅ **Fix 1 abgeschlossen:** "Generate twice" Problem behoben
-2. ✅ **Fix 2 abgeschlossen:** Drift-Erkennung in Validierung integriert
-3. ✅ **Fix 3 abgeschlossen:** Signatur-Validierung für optionale Felder verbessert
-4. ⏭️ **Manuelle Tests:** Alle drei Fixes manuell testen
-5. ⏭️ **README aktualisiert:** Fixes dokumentiert
-
-## Referenzen
-
-- **Plan:** `system.plan.md` (System-Funktionalitäts-Analyse und Fixes)
-- **ADR 011:** Modul-Dokumente mit Änderungs-Kommentaren (Phase 3)
-- **ADR 012:** Git-Deletions und CHANGE_REPORT (Phase 4)
-- **Dokumentation:**
-  - `docs/modules/src__extension.ts.md`
-  - `docs/modules/src__drift__index.ts.md`
-  - `docs/modules/src__validator__signature-matching.ts.md`
-  - `docs/modules/src__parsers__types.ts.md`
-
-## Implementierung
-
-**Dateien:**
-- `src/extension.ts` (geändert, ~50 Zeilen)
-  - `generateDocumentationTs()`: Vereinfachte Logik für ersten Lauf
-  - `validateDocumentationTs()`: Drift-Erkennung integriert
-- `src/validator/signature-matching.ts` (geändert, ~30 Zeilen)
-  - `formatSignatureForDoc()`: Optionale Felder berücksichtigen
-  - `isOptionalFieldCompatible()`: Neue Funktion für Kompatibilitätsprüfung
-- `README.md` (aktualisiert): Fixes dokumentiert
-
-**Geänderte Zeilen:** ~80 Zeilen  
-**Neue Funktionen:** 1 (`isOptionalFieldCompatible`)  
-**Entfernte Funktionen:** Komplexe Fallback-Logik (Zeilen 199-268)
-
-**Qualität:**
-- ✅ TypeScript kompiliert ohne Fehler
-- ✅ Rückwärtskompatibel (keine Breaking Changes)
-- ✅ Deterministisch (gleiche Eingabe → gleiche Ausgabe)
-- ✅ Keine zirkulären Abhängigkeiten
-- ✅ Besseres Logging für Debugging
-
-**Erwartete Verbesserungen:**
-- Beim ersten Lauf werden alle Dateien erkannt (kein "generate twice" mehr)
-- Drift wird in Validierungs-UI angezeigt (Status gelb bei Drift)
-- Optionale Felder werden als kompatibel erkannt (weniger falsche Mismatches)
-

package/docs/adr/014-rules-migration-und-mcp-integration.md

@@ -1,113 +0,0 @@
-# ADR-014: Rules-Migration und MCP-Integration
-
-## Status
-
-Accepted
-
-## Kontext
-
-Das Projekt nutzte bisher zwei Always-Apply Rules (`mvp-plan.mdc` und `architecture-guardrails.mdc`), die:
-- Fest auf `MVP_PLAN.md` und `ADDITIVE_DOCUMENTATION_PLAN.md` verwiesen
-- Keine kontextspezifische Aktivierung unterstützten
-- Keine Agent-Requested Workflows definierten
-- Keine Memory-Guidelines enthielten
-
-Mit Abschluss des MVP war eine Neustrukturierung erforderlich, um:
-1. Veraltete MVP-Referenzen zu entfernen
-2. Kontextsensitive Rules (Auto-Attached) einzuführen
-3. Agent-Requested Workflows für explizite Anfragen zu definieren
-4. Dynamische Plan-Erkennung zu implementieren
-5. MCP-Server für strukturierte Tool-Integration vorzubereiten
-
-## Entscheidung
-
-### 1. Neue Rule-Struktur
-
-```
-.cursor/rules/
-├── 000-orchestrator.mdc        # Always – Zentrale Steuerung
-├── 001-pre-check.mdc           # Always – Pflichtschritte vor Änderungen
-├── 010-parsers.mdc             # Auto-Attached: src/parsers/**
-├── 011-validators.mdc          # Auto-Attached: src/validator/**
-├── 012-cache.mdc               # Auto-Attached: src/cache/**
-├── 013-generator.mdc           # Auto-Attached: src/generator/**
-├── 020-validate-workflow.mdc   # Agent-Requested: "validiere", "prüfe"
-├── 021-impact-analysis.mdc     # Agent-Requested: "Auswirkungen", "Dependencies"
-├── 022-adr-workflow.mdc        # Agent-Requested: "ADR schreiben"
-└── 030-constraints.mdc         # Always – Architektur-Constraints
-```
-
-### 2. Dynamische Plan-Erkennung
-
-Statt fest auf `MVP_PLAN.md` zu verweisen:
-- Suche nach `*.plan.md` im Projekt-Root
-- Priorisierung: Spezifische Pläne vor allgemeinen
-- Fallback auf Standard-Constraints bei fehlendem Plan
-- Plan-Abweichungen müssen als ADR dokumentiert werden
-
-### 3. MCP-Server für Validierungs-Tools
-
-Neuer MCP-Server in `mcp/` mit:
-- `validation/runScan` – Dokumentations-Scan
-- `validation/runValidate` – Validierung
-- `validation/runDriftCheck` – Drift-Detection
-- `validation/analyzeImpact` – Impact-Analyse
-
-Vorteile:
-- Strukturierte JSON-Responses statt Freitext
-- Teilvalidierung einzelner Dateien
-- Bessere Integration mit Agent-Workflows
-
-### 4. Memory-Guidelines
-
-In `000-orchestrator.mdc` definiert:
-- **Speichern**: ADR-Entscheidungen, Arbeitsmuster, Konventionen
-- **Nicht speichern**: Temporäre Fehler, experimentelle Ideen
-- **Widerspruchs-Handling**: Bei Repo-Widerspruch Memory prüfen/löschen
-
-## Konsequenzen
-
-### Positive
-
-- **Reduzierter Token-Verbrauch**: Auto-Attached Rules laden nur bei Bedarf
-- **Klarere Struktur**: Trennung von Always/Auto-Attached/Agent-Requested
-- **Flexibilität**: Dynamische Plan-Erkennung statt statischer Referenzen
-- **Bessere Tool-Integration**: MCP-Server für strukturierte Validierung
-- **Persistentes Lernen**: Memory-Guidelines für konsistentes Verhalten
-
-### Negative
-
-- **Initiale Komplexität**: Mehr Rule-Dateien zu pflegen
-- **MCP-Server-Wartung**: Zusätzlicher Code in `mcp/`
-- **Migration**: Alte Rules müssen entfernt/archiviert werden
-
-## Alternativen
-
-### Alternative A: Bestehende Rules beibehalten
-
-Abgelehnt, weil:
-- Veraltete MVP-Referenzen verwirrend
-- Keine kontextsensitive Aktivierung
-- Keine Agent-Requested Workflows
-
-### Alternative B: Nur Always-Apply Rules
-
-Abgelehnt, weil:
-- Höherer Token-Verbrauch
-- Keine modul-spezifischen Leitplanken
-- Keine expliziten Workflow-Trigger
-
-### Alternative C: MCP-Server in separatem Repo
-
-Abgelehnt, weil:
-- Engere Integration mit Projekt-Tooling gewünscht
-- Einfachere Wartung im selben Repo
-- Direkter Zugriff auf `docs/` und CLI-Kommandos
-
-## Referenzen
-
-- `000-orchestrator.mdc` – Zentrale Workflow-Steuerung
-- `001-pre-check.mdc` – Pre-Check Checkliste
-- `020-validate-workflow.mdc` – MCP-Server Integration
-- `mcp/README.md` – MCP-Server Dokumentation
-

package/docs/adr/015-global-agent-package.md

@@ -1,158 +0,0 @@
-# ADR-015: Globales Agent-Package @benni/doc-system-agent
-
-## Status
-
-Accepted
-
-## Kontext
-
-Das Projekt hat eine funktionierende Dokumentations-Engine (VS Code Extension) und 
-einen MCP-Server für strukturierte Validierung entwickelt. Zusätzlich wurden 
-`.cursor/rules/` für AI-Agent-Workflows erstellt.
-
-Diese Komponenten waren bisher nur in diesem einen Repo verfügbar. Um dieselbe 
-Arbeitsweise in neuen Projekten nutzen zu können, war eine Lösung erforderlich, 
-die:
-
-1. Die Rules und den MCP-Server portabel macht
-2. Einfache Installation in neuen Projekten ermöglicht
-3. Versionierung und Updates unterstützt
-4. Sowohl mit Cursor (AI-Agent) als auch VS Code (Extension) funktioniert
-
-## Entscheidung
-
-### Neues npm-Package: @benni/doc-system-agent
-
-Ein eigenständiges npm-Package, das alle Agent-relevanten Komponenten bündelt:
-
-```
-packages/doc-system-agent/
-├── src/
-│   ├── cli/           # CLI-Kommandos (init, update, info)
-│   ├── mcp/           # MCP-Server + Tools
-│   └── index.ts       # Public API
-├── templates/
-│   └── cursor-rules/  # Rule-Templates (.mdc)
-├── examples/
-│   └── basic-project/ # Beispielprojekt
-├── package.json
-└── README.md
-```
-
-### CLI-Kommandos
-
-```bash
-# Projekt initialisieren
-npx doc-agent init [--force] [--merge] [--verbose]
-
-# Rules aktualisieren
-npx doc-agent update [--safe] [--verbose]
-
-# Info anzeigen
-npx doc-agent info
-
-# MCP-Server starten
-npx doc-mcp-server start
-```
-
-### Programmatic API
-
-```typescript
-import { initProject, updateRules, startMcpServer } from '@benni/doc-system-agent';
-
-await initProject({ targetDir: './my-project', merge: true });
-await updateRules({ safe: true });
-await startMcpServer();
-```
-
-### Rules-Versionierung
-
-```json
-// .cursor/rules/.rules-version.json
-{
-  "version": 1,
-  "updatedAt": "2024-12-01"
-}
-```
-
-- Bei `init`: Version wird gesetzt
-- Bei `update`: Alte Version → Neue Version, mit Backup
-- Bei `update --safe`: Neue Dateien als `.new` ablegen
-
-## Konsequenzen
-
-### Positive
-
-- **Portabilität**: Dieselbe Arbeitsweise in jedem Projekt
-- **Einfache Installation**: Ein `npx`-Befehl genügt
-- **Versionierung**: Kontrollierte Updates ohne Datenverlust
-- **Separation of Concerns**: Agent-Tooling getrennt von Extension
-- **Wiederverwendbarkeit**: Rules und MCP-Server als wiederverwendbare Assets
-
-### Negative
-
-- **Zusätzliche Wartung**: Ein weiteres Package zu pflegen
-- **Synchronisation**: Rules müssen zwischen Repos synchron gehalten werden
-- **Abhängigkeit**: Neue Projekte hängen vom Package ab
-
-## Alternativen
-
-### Alternative A: Template-Repository
-
-Ein GitHub-Template-Repo, das geklont wird.
-
-Abgelehnt, weil:
-- Keine einfachen Updates möglich
-- Keine Versionierung
-- Schwieriger in bestehende Projekte zu integrieren
-
-### Alternative B: Nur .cursor/rules kopieren
-
-Manuelles Kopieren der Rule-Dateien.
-
-Abgelehnt, weil:
-- Fehleranfällig
-- Keine Versionierung
-- MCP-Server-Setup nicht enthalten
-
-### Alternative C: Monorepo mit Workspaces
-
-Alles in einem Monorepo mit npm/yarn workspaces.
-
-Teilweise umgesetzt (Package liegt in `packages/`), aber:
-- Package ist eigenständig publishbar
-- Kann unabhängig versioniert werden
-
-## Verwendung
-
-### Neues Projekt starten
-
-```bash
-mkdir my-new-project && cd my-new-project
-npm init -y
-npm install -D @benni/doc-system-agent
-npx doc-agent init --verbose
-```
-
-### Bestehendes Projekt erweitern
-
-```bash
-cd existing-project
-npm install -D @benni/doc-system-agent
-npx doc-agent init --merge  # Nur fehlende Rules ergänzen
-```
-
-### Rules aktualisieren
-
-```bash
-npx doc-agent update --safe  # Neue Versionen als .new-Dateien
-# Manuell prüfen und mergen
-npx doc-agent update         # Direkt überschreiben (mit Backup)
-```
-
-## Referenzen
-
-- [Package README](../../packages/doc-system-agent/README.md)
-- [VS Code Integration](../../packages/doc-system-agent/VSCODE_INTEGRATION.md)
-- [ADR-014: Rules-Migration](./014-rules-migration-und-mcp-integration.md)
-