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

package/docs/adr/016-produktisierung-docguard.md

@@ -1,193 +0,0 @@
-# ADR-016: Produktisierung als DocGuard
-
-## Status
-
-Akzeptiert
-
-## Datum
-
-2024-12-01
-
-## Kontext
-
-Das Documentation System Plugin war bisher ein internes Tool zur automatischen Dokumentationsgenerierung. Es wurde entschieden, das System als vollwertiges Produkt zu positionieren, um:
-
-1. **Portfolio-Showcase**: Technische Expertise demonstrieren
-2. **Marktpositionierung**: Differenzierung gegenüber TypeDoc, JSDoc, Mintlify
-3. **Monetarisierungspotenzial**: Gestaffeltes Pricing-Modell ermöglichen
-
-## Entscheidung
-
-Das System wird unter dem Markennamen **DocGuard** produktisiert mit dem Claim "Documentation that never drifts".
-
-### 1. Branding & Identität
-
-| Element | Wert |
-|---------|------|
-| Produktname | DocGuard |
-| Tagline | "Documentation that never drifts" |
-| Primary Color | Guard Blue `#2563EB` |
-| Success | `#10B981` |
-| Warning (Drift) | `#F59E0B` |
-| Fonts | JetBrains Mono (Code), Inter (UI) |
-
-**Dateien:**
-- `BRANDING.md` – Vollständige Brand Guidelines
-
-### 2. Package-Struktur (npm)
-
-| Package | Name | Beschreibung |
-|---------|------|--------------|
-| CLI | `@docguard/cli` | Standalone CLI für CI/CD |
-| MCP | `@docguard/mcp` | AI-Agent Integration |
-| Extension | `docguard` | VS Code Extension |
-
-**Geänderte Dateien:**
-- `package.json` (Root)
-- `packages/doc-system-agent/package.json`
-- `mcp/package.json`
-
-### 3. Dokumentation & Community
-
-Neue Dateien für Open-Source-Professionalisierung:
-
-| Datei | Zweck |
-|-------|-------|
-| `README.md` | Professionelle Produktpräsentation |
-| `CONTRIBUTING.md` | Contribution Guidelines |
-| `CODE_OF_CONDUCT.md` | Verhaltenskodex |
-| `.github/ISSUE_TEMPLATE/` | Bug Reports, Feature Requests |
-| `.github/PULL_REQUEST_TEMPLATE.md` | PR-Template |
-
-### 4. Landing Page (`website/`)
-
-Technologie-Stack:
-- **Framework**: Astro 4.x
-- **Styling**: Tailwind CSS 3.x
-- **Deployment**: Vercel (geplant)
-
-Komponenten:
-- Hero mit Terminal-Demo
-- Features Grid
-- Pricing-Tabelle (Free/Pro/Team/Enterprise)
-- Quick Start Guide
-- Footer
-
-### 5. CI/CD & GitHub Actions
-
-| Workflow | Datei | Funktion |
-|----------|-------|----------|
-| CI | `.github/workflows/ci.yml` | Build, Test, Package |
-| Publish | `.github/workflows/publish.yml` | npm, VS Code Marketplace, Website |
-
-Wiederverwendbare Action für andere Projekte:
-- `action/action.yml` – DocGuard Validation Action
-- Unterstützt: scan, generate, validate, drift
-- PR-Kommentare mit Validation Report
-
-### 6. Demo-Projekt (`demo/`)
-
-Beispiel-Projekt mit:
-- Source Code (`calculator.ts`, `user-service.ts`, `types.ts`)
-- Generierter Dokumentation
-- Drift-Beispiel (absichtlich veraltete Docs)
-- Change Report
-
-### 7. Pricing-Modell
-
-| Tier | Preis | Features |
-|------|-------|----------|
-| Free | $0 | Extension, CLI, Local Drift-Detection |
-| Pro | $19/mo | Cloud Dashboard, Email Alerts |
-| Team | $49/seat | Analytics, Slack/Teams, RBAC |
-| Enterprise | Custom | SSO, Audit Logs, Compliance |
-
-## Konsequenzen
-
-### Positiv
-
-1. **Professionelle Außenwirkung**: Vollständige Produktpräsentation
-2. **Skalierbarkeit**: Klare Tier-Struktur für zukünftige Monetarisierung
-3. **Community-Ready**: Issue Templates, Contributing Guide
-4. **CI/CD-Integration**: GitHub Action für breite Adoption
-
-### Negativ / Risiken
-
-1. **Wartungsaufwand**: Mehr Artefakte zu pflegen (Website, Docs, etc.)
-2. **Namespace-Konflikte**: `@docguard` Scope muss auf npm registriert werden
-3. **Breaking Change**: Package-Namen ändern sich von `@benni/` zu `@docguard/`
-
-### Neutral
-
-1. **Keine Code-Änderungen**: Kern-Funktionalität bleibt unverändert
-2. **Inkrementeller Rollout**: Features können schrittweise aktiviert werden
-
-## Betroffene Dateien
-
-### Neue Dateien
-
-```
-BRANDING.md
-CONTRIBUTING.md
-CODE_OF_CONDUCT.md
-.github/ISSUE_TEMPLATE/bug_report.md
-.github/ISSUE_TEMPLATE/feature_request.md
-.github/ISSUE_TEMPLATE/config.yml
-.github/PULL_REQUEST_TEMPLATE.md
-.github/workflows/ci.yml
-.github/workflows/publish.yml
-action/action.yml
-action/README.md
-assets/icon.svg
-website/package.json
-website/astro.config.mjs
-website/tailwind.config.mjs
-website/tsconfig.json
-website/README.md
-website/public/favicon.svg
-website/src/layouts/Layout.astro
-website/src/pages/index.astro
-website/src/components/Header.astro
-website/src/components/Hero.astro
-website/src/components/Features.astro
-website/src/components/HowItWorks.astro
-website/src/components/QuickStart.astro
-website/src/components/Pricing.astro
-website/src/components/Footer.astro
-demo/README.md
-demo/package.json
-demo/docguard.config.json
-demo/src/types.ts
-demo/src/calculator.ts
-demo/src/user-service.ts
-demo/docs/modules/*.md
-demo/docs/system/*.md
-```
-
-### Geänderte Dateien
-
-```
-README.md (komplett neu)
-package.json (Name, Metadata, Commands, Keybindings)
-packages/doc-system-agent/package.json (Name → @docguard/cli)
-packages/doc-system-agent/README.md (komplett neu)
-mcp/package.json (Name → @docguard/mcp)
-tsconfig.json (Excludes für demo, website, action)
-```
-
-## Offene Punkte (manuelle Schritte)
-
-1. [ ] npm Scope `@docguard` registrieren
-2. [ ] GitHub Organisation `docguard` erstellen
-3. [ ] Domain `docguard.dev` registrieren
-4. [ ] Vercel-Projekt einrichten
-5. [ ] VS Code Marketplace Publisher erstellen
-6. [ ] Screenshots und Demo-GIFs erstellen
-7. [ ] Bestehende Installation migrieren (falls nötig)
-
-## Referenzen
-
-- [produktisierung.plan.md](../../produktisierung.plan.md) – Ursprünglicher Plan
-- [BRANDING.md](../../BRANDING.md) – Brand Guidelines
-- [README.md](../../README.md) – Produkt-README
-

package/docs/adr/017-signature-matching-optional-fields.md

@@ -1,128 +0,0 @@
-# ADR-017: Verbesserte Optional-Feld-Kompatibilität in Signatur-Validierung
-
-## Status
-
-Akzeptiert
-
-## Datum
-
-2024-12-01
-
-## Kontext
-
-Die Dokumentations-Validierung meldete 30 Signatur-Abweichungs-Warnungen für Interfaces, bei denen sich nur die Optionalität von Properties unterschied:
-
-```
-erwartet:    "interface DriftItem { expected: string; ... }"
-dokumentiert: "interface DriftItem { expected?: string; ... }"
-```
-
-Das Problem: Die `isOptionalFieldCompatible`-Funktion konnte mehrzeilige Interface-Definitionen nicht korrekt vergleichen, da sie nur einzeilige Signaturen normalisierte.
-
-## Entscheidung
-
-Die `isOptionalFieldCompatible`-Funktion in `src/validator/signature-matching.ts` wurde komplett überarbeitet:
-
-### Vorher
-
-```typescript
-function isOptionalFieldCompatible(expected: string, documented: string): boolean {
-    const normalize = (s: string) => s.replace(/\s+/g, ' ').trim();
-    // ... einfache String-Ersetzung
-    const removeOptional = (s: string) => s.replace(/(\w+)\?(\s*:)/g, '$1$2');
-    return removeOptional(expectedNorm) === removeOptional(documentedNorm);
-}
-```
-
-### Nachher
-
-```typescript
-function isOptionalFieldCompatible(expected: string, documented: string): boolean {
-    // 1. Robuste Normalisierung für mehrzeilige Interfaces
-    const normalizeForComparison = (s: string) => {
-        return s
-            .replace(/\s+/g, ' ')      // Alle Whitespaces normalisieren
-            .replace(/\s*:\s*/g, ':')   // Spaces um Doppelpunkte
-            .replace(/\s*;\s*/g, ';')   // Spaces um Semikolons
-            .replace(/\s*\{\s*/g, '{')  // Spaces um Klammern
-            .replace(/\s*\}\s*/g, '}')
-            .replace(/\s*\|\s*/g, '|')  // Union Types
-            .trim();
-    };
-    
-    // 2. Optional-Marker entfernen
-    const removeOptionalMarkers = (s: string) => s.replace(/(\w+)\?:/g, '$1:');
-    
-    // 3. Feld-basierter Vergleich
-    const extractFields = (s: string): Map<string, string> => {
-        const fields = new Map<string, string>();
-        const fieldRegex = /(\w+)\??:\s*([^;}\n]+)/g;
-        // ... Felder extrahieren
-        return fields;
-    };
-    
-    // Vergleiche Felder unabhängig von Optionalität
-    // ...
-}
-```
-
-### Verbesserungen
-
-1. **Mehrzeilige Interfaces**: Zeilenumbrüche werden korrekt normalisiert
-2. **Robuster Vergleich**: Felder werden einzeln extrahiert und verglichen
-3. **Typ-Fokus**: Nur Name und Typ werden verglichen, Optionalität wird ignoriert
-
-## Konsequenzen
-
-### Positiv
-
-1. **Weniger False Positives**: Interfaces mit unterschiedlicher Optionalität werden als kompatibel erkannt
-2. **Bessere Developer Experience**: Weniger irrelevante Warnungen
-3. **Korrekte Semantik**: `field: T` und `field?: T` sind architektonisch äquivalent
-
-### Negativ
-
-1. **Potenzielle False Negatives**: Echte Breaking Changes bei Optionalität werden nicht mehr gemeldet
-   - Mitigiert durch: Coverage-Checks und manuelle Reviews
-
-## Betroffene Dateien
-
-```
-src/validator/signature-matching.ts
-```
-
-## Tests
-
-Alle bestehenden Tests bestanden:
-```
-PASS src/__tests__/determinism.test.ts
-  ✓ Wiederholte Scans erzeugen identische Ergebnisse
-  ✓ Parser erzeugt deterministische Symbole
-  ✓ Generator erzeugt deterministische Markdown
-```
-
-## Zusätzliche Änderungen
-
-### tsconfig.json
-
-Neue Verzeichnisse zur Exclude-Liste hinzugefügt:
-```json
-"exclude": [
-    "node_modules",
-    ".vscode-test",
-    "mcp",
-    "packages",
-    "demo",      // NEU
-    "website",   // NEU
-    "action"     // NEU
-]
-```
-
-### package.json
-
-Nicht existierende Skripte entfernt:
-```diff
-- "scan": "node out/cli-scan.js",
-- "validate": "node out/cli-validate.js",
-```
-

package/docs/adr/018-rebranding-docguard-to-noyrax.md

@@ -1,109 +0,0 @@
-# ADR-018: Rebranding von DocGuard zu Noyrax
-
-## Status
-
-Akzeptiert
-
-## Datum
-
-2024-12-01
-
-## Kontext
-
-Nach der initialen Produktisierung unter dem Namen "DocGuard" (ADR-016) wurde entschieden, das Produkt zu "Noyrax" umzubenennen.
-
-## Entscheidung
-
-Vollständiges Rebranding des Produkts:
-
-| Alt | Neu |
-|-----|-----|
-| DocGuard | Noyrax |
-| @docguard/* | @noyrax/* |
-| docguard.dev | noyrax.dev |
-| DG (Logo) | NX (Logo) |
-| guard-blue | noyrax-blue |
-| --dg-* (CSS) | --nx-* (CSS) |
-
-### Betroffene Bereiche
-
-1. **Package-Namen**
-   - `docguard` → `noyrax` (VS Code Extension)
-   - `@docguard/cli` → `@noyrax/cli`
-   - `@docguard/mcp` → `@noyrax/mcp`
-
-2. **Commands & Keybindings**
-   - `docguard.*` → `noyrax.*`
-   - `Ctrl+Shift+D` → `Ctrl+Shift+N`
-
-3. **Configuration**
-   - `docguard.*` → `noyrax.*` (VS Code Settings)
-   - `docguard.config.json` → `noyrax.config.json`
-
-4. **URLs**
-   - `https://docguard.dev` → `https://noyrax.dev`
-   - `github.com/docguard/*` → `github.com/noyrax/*`
-
-5. **Branding**
-   - Logo: "DG" → "NX"
-   - CSS Variables: `--dg-*` → `--nx-*`
-   - Tailwind: `guard-blue` → `noyrax-blue`
-
-## Geänderte Dateien
-
-### Hauptkonfiguration
-- `package.json`
-- `packages/doc-system-agent/package.json`
-- `mcp/package.json`
-- `website/package.json`
-- `demo/package.json`
-
-### Branding & Dokumentation
-- `BRANDING.md`
-- `README.md`
-- `CONTRIBUTING.md`
-- `CODE_OF_CONDUCT.md`
-- `packages/doc-system-agent/README.md`
-
-### Website
-- `website/astro.config.mjs`
-- `website/tailwind.config.mjs`
-- `website/src/layouts/Layout.astro`
-- `website/src/components/*.astro` (alle Komponenten)
-- `website/public/favicon.svg`
-
-### GitHub
-- `action/action.yml`
-- `action/README.md`
-- `.github/workflows/ci.yml`
-- `.github/ISSUE_TEMPLATE/*.md`
-
-### Demo
-- `demo/README.md`
-- `demo/docguard.config.json`
-- `demo/docs/**/*.md`
-
-### Assets
-- `assets/icon.svg`
-
-## Konsequenzen
-
-### Positiv
-1. **Einzigartiger Name**: "Noyrax" ist einprägsamer und weniger generisch
-2. **Namespace-Verfügbarkeit**: Höhere Wahrscheinlichkeit, dass `@noyrax` auf npm verfügbar ist
-3. **Domain-Verfügbarkeit**: `noyrax.dev` ist möglicherweise noch verfügbar
-
-### Negativ
-1. **ADR-016 veraltet**: Das vorherige Produktisierungs-ADR referenziert "DocGuard"
-2. **Keine Migration**: Bestehende Installationen müssen manuell umgestellt werden
-
-### Zu erledigen
-1. [ ] `@noyrax` Scope auf npm registrieren
-2. [ ] `noyrax.dev` Domain registrieren
-3. [ ] GitHub Organisation `noyrax` erstellen
-4. [ ] VS Code Marketplace Publisher erstellen
-
-## Referenzen
-
-- [ADR-016: Produktisierung als DocGuard](./016-produktisierung-docguard.md) (veraltet, jetzt Noyrax)
-

package/docs/adr/019-system-schwachstellen-analyse-und-fixes.md

@@ -1,204 +0,0 @@
-# ADR-019: System-Schwachstellen-Analyse und proaktive Fixes
-
-**Status:** Implementiert  
-**Datum:** 2025-12-02  
-**Kontext:** Gründliche Analyse der Dokumentationsartefakte zur Identifikation von System-Schwachstellen
-
-## Kontext und Problemstellung
-
-Eine detaillierte Analyse der generierten Dokumentation (`docs/system/`, `docs/index/`, `docs/modules/`) und der historischen ADRs (001-018) wurde durchgeführt, um:
-
-1. Bereits behobene Probleme zu verifizieren
-2. Noch bestehende Schwachstellen zu identifizieren
-3. Proaktive Maßnahmen für zukünftige Entwicklung zu definieren
-
-### Analysierte Artefakte
-
-- `docs/system/CHANGE_REPORT.md` - 900+ "Geänderte Symbole" Einträge
-- `docs/index/symbols.jsonl` - 95 Einträge aus `.ai-agent-context/`
-- `docs/system/DEPENDENCIES.md` - Abhängigkeitsübersicht
-- ADR-001 bis ADR-018 - Historische Fixes
-
-### Identifizierte Schwachstellen
-
-1. **Scanner filtert relevante Verzeichnisse nicht aus**
-   - `.ai-agent-context` wird gescannt → 95 irrelevante Symbole im Index
-   - `.vscode`, `.cursor` werden gescannt
-
-2. **Generator/Validator Formatierungs-Differenz**
-   - Generator: `${p.name}${p.type ? ...}` (ohne optional)
-   - Validator: `${p.name}${p.optional ? '?' : ''}${p.type ? ...}`
-   - Potenzielle False-Positive-Mismatches bei optionalen Parametern
-
-3. **Keine zentrale Signatur-Formatierung**
-   - Generator und Validator haben separate Implementierungen
-   - Inkonsistenzen schwer zu erkennen
-
-4. **Fehlende Pre-Planning-Richtlinien**
-   - Agent-Fehler werden erst nach Implementierung entdeckt
-   - Keine proaktiven Checklisten
-
-## Entscheidung
-
-### Fix 1: Scanner-Exclude-Liste erweitern
-
-**Datei:** `src/core/scanner.ts`
-
-```typescript
-const DEFAULT_EXCLUDES = new Set([
-    'node_modules',
-    '.git', '.svn', '.hg',
-    'dist', 'out', 'build',
-    '__pycache__', '.mypy_cache', '.venv', '.cache',
-    'docs', // Generierte Dokumentation
-    '.ai-agent-context', // AI-Agent-Kontext (Backups, Metadaten)
-    '.vscode', // VS Code Workspace-Einstellungen
-    '.cursor', // Cursor IDE Einstellungen
-]);
-```
-
-**Auswirkung:** Symbol-Index enthält keine irrelevanten Backup-Dateien mehr.
-
-### Fix 2: Generator-Formatierung für optionale Parameter
-
-**Datei:** `src/generator/module-doc.ts`
-
-```typescript
-// VORHER:
-const params = block.symbol.signature.parameters
-    .map(p => `${p.name}${p.type ? `: ${p.type}` : ''}${p.hasDefault ? ' = …' : ''}`)
-    .join(', ');
-
-// NACHHER:
-const params = block.symbol.signature.parameters
-    .map(p => `${p.name}${p.optional ? '?' : ''}${p.type ? `: ${p.type}` : ''}${p.hasDefault ? ' = …' : ''}`)
-    .join(', ');
-```
-
-**Auswirkung:** Generator und Validator formatieren Funktions-Parameter identisch.
-
-### Fix 3: Zentrale SignatureFormatter-Klasse
-
-**Neue Datei:** `src/core/signature-formatter.ts`
-
-```typescript
-export class SignatureFormatter {
-    static formatForDoc(symbol: ParsedSymbol): string { ... }
-    static normalize(signature: string): string { ... }
-    static normalizeSignature(sig: SymbolSignature): string { ... }
-    static compare(expected: string, documented: string, options?: CompareOptions): CompareResult { ... }
-}
-```
-
-**Auswirkung:** Einheitliche Logik für Generator und Validator; einfachere Wartung.
-
-### Fix 4: Pre-Planning Checklisten als Cursor Rule
-
-**Neue Datei:** `.cursor/rules/023-pre-planning.mdc`
-
-Enthält Checklisten für:
-- Scanner-Änderungen
-- Parser-Änderungen
-- Validator-Änderungen
-- Generator-Änderungen
-- Cache-Änderungen
-
-**Auswirkung:** Agent kann Fehler proaktiv vermeiden.
-
-### Fix 5: Erweiterte Parser-Test-Suite
-
-**Neue Datei:** `src/__tests__/parser-symbol-types.test.ts`
-
-18 neue Tests für:
-- Alle Symbol-Typen (class, interface, type, enum, function, method, variable, module)
-- Edge-Cases (leere Dateien, Syntax-Fehler, komplexe Generics)
-- SignatureFormatter-Konsistenz
-
-## Gelesene Abhängigkeiten aus Dokumentation
-
-**docs/modules/src__core__scanner.ts.md:**
-- `DEFAULT_EXCLUDES: Set<string>`
-- `scanWorkspace(options: ScanOptions, includeBackups: boolean): ScannedFile[]`
-
-**docs/modules/src__generator__module-doc.ts.md:**
-- `renderModuleDoc(doc: ModuleDoc, filePath: string): string`
-
-**docs/modules/src__validator__signature-matching.ts.md:**
-- `formatSignatureForDoc(symbol: ParsedSymbol): string`
-
-## Auswirkungen
-
-### Positiv
-
-- ✅ **Sauberer Symbol-Index:** Keine irrelevanten Backup-Dateien mehr
-- ✅ **Konsistente Formatierung:** Generator und Validator sind synchron
-- ✅ **Zentrale Signatur-Logik:** Einfachere Wartung und Erweiterung
-- ✅ **Proaktive Fehlervorbeugung:** Pre-Planning-Checklisten
-- ✅ **Bessere Test-Abdeckung:** 18 neue Tests für Symbol-Typen
-
-### Neutral
-
-- ~150 Zeilen neue Klasse (SignatureFormatter)
-- ~250 Zeilen neue Tests
-- 1 neue Cursor Rule
-
-### Risiken und Mitigation
-
-- **Risiko:** SignatureFormatter wird nicht sofort in Generator/Validator integriert
-  - **Mitigation:** Klasse ist als Drop-in-Ersatz konzipiert; Migration kann schrittweise erfolgen
-
-- **Risiko:** Neue Tests könnten bei Parser-Änderungen fehlschlagen
-  - **Mitigation:** Tests prüfen Verhalten, nicht exakte Ausgabe
-
-## Verifizierte Fixes aus früheren ADRs
-
-Die Analyse hat bestätigt, dass folgende Fixes korrekt implementiert sind:
-
-| ADR | Fix | Verifiziert |
-|-----|-----|-------------|
-| ADR-004 | Symbol-typ-spezifische Formatierung | ✅ Zeilen 55-84 in signature-matching.ts |
-| ADR-005 | TypeNode vor getType() | ✅ Zeilen 56-64 in ts-js.ts |
-| ADR-006 | Variablen-Typen präziser | ✅ Zeilen 229-255 in ts-js.ts |
-| ADR-007 | Standard-Libs laden | ✅ Zeilen 16, 25 in ts-js.ts |
-| ADR-008 | Dependencies-Cache | ✅ consolidation.ts |
-| ADR-013 | isFirstRun vor Git-Filter | ✅ Zeilen 130-155 in extension.ts |
-| ADR-017 | Optional-Feld-Kompatibilität | ✅ Zeilen 211-277 in signature-matching.ts |
-
-## Implementierte Dateien
-
-| Datei | Änderung | Zeilen |
-|-------|----------|--------|
-| `src/core/scanner.ts` | DEFAULT_EXCLUDES erweitert | +3 |
-| `src/generator/module-doc.ts` | Optional-Parameter-Fix | +1 |
-| `src/core/signature-formatter.ts` | Neue zentrale Klasse | +160 |
-| `.cursor/rules/023-pre-planning.mdc` | Neue Pre-Planning Rule | +180 |
-| `src/__tests__/parser-symbol-types.test.ts` | Erweiterte Test-Suite | +250 |
-
-## Tests
-
-```
-npm test
-
- PASS  src/__tests__/determinism.test.ts
- PASS  src/__tests__/parser-symbol-types.test.ts
-
-Test Suites: 2 passed, 2 total
-Tests:       21 passed, 21 total
-```
-
-## Nächste Schritte (optional)
-
-1. **SignatureFormatter in Generator/Validator integrieren** - Migration der bestehenden Formatierungs-Logik
-2. **JSON-Parser semantische Filterung** - Whitelist für relevante JSON-Dateien
-3. **Re-Export als eigener Symbol-Typ** - `kind: 'reexport'` statt `kind: 'variable'`
-4. **Konfigurierbare Toleranz-Patterns** - Config-Datei statt hardcoded
-
-## Referenzen
-
-- **Analyse:** System-Schwachstellen-Analyse (Konversation)
-- **ADRs:** ADR-001 bis ADR-018 (verifizierte Fixes)
-- **Dokumentation:**
-  - `docs/modules/src__core__scanner.ts.md`
-  - `docs/modules/src__generator__module-doc.ts.md`
-  - `docs/modules/src__validator__signature-matching.ts.md`
-

package/docs/adr/020-api-doc-tiefe-und-signatureformatter.md

@@ -1,74 +0,0 @@
-# ADR-020: API-Doku-Tiefe & zentrale Signatur-Formatierung
-
-**Status:** Implementiert  
-**Datum:** 2025-12-04  
-
-## Kontext
-
-Noyrax soll als Produkt auch komplexe Systeme wie das Database-Plugin
-präzise dokumentieren. Die Analyse der Validierungsberichte zeigte:
-
-- Sehr detailliertes Signaturwissen in Parsern/Index/Database
-- Gleichzeitig nur oberflächliche, teilweise leere API-Doku in
-  `docs/modules/` (nur Namen, leere Interfaces)
-- Daraus resultierten hunderte Signatur-Abweichungs-Warnungen
-
-Bisher nutzten Generator (`renderModuleDoc`) und Validator
-(`validateSignatureMatching`) jeweils eigene Formatierungslogik.
-Toleranzen (optionale Felder, Generics) waren verteilt implementiert.
-
-## Entscheidung
-
-1. Einführung einer zentralen `SignatureFormatter`-Klasse in
-   `src/core/signature-formatter.ts`:
-   - `formatForDoc(symbol)` rendert Signaturen deterministisch und
-     menschenlesbar (Funktionen, Methoden, Interfaces, Variablen).
-   - `compare(expected, documented, options)` kapselt Toleranzen:
-     - optionale Felder (`field` vs `field?`)
-     - generische Vereinfachungen (`T[]` vs `{}`)
-
-2. Ausrichtung von Generator und Validator auf `SignatureFormatter`:
-   - `src/generator/module-doc.ts`:
-     - nutzt `SignatureFormatter.formatForDoc()` für alle Signaturen
-     - ergänzt tiefe API-Doku:
-       - einzeilige Signatur-Zeile
-       - Tabellen für Parameter / Eigenschaften
-       - expliziter Rückgabewert-Abschnitt
-   - `src/validator/signature-matching.ts`:
-     - verwendet `SignatureFormatter.formatForDoc()` als „expected“
-     - nutzt `SignatureFormatter.compare()` für den Abgleich
-     - dedupliziert identische Abweichungen
-     - berücksichtigt nur öffentliche Symbole, sofern nicht anders
-       konfiguriert
-
-3. Ergänzung einer Pre-Planning-Rule
-   (`.cursor/rules/024-api-doc-depth.mdc`) mit Checklisten für:
-   - API-Doku-Tiefe und Signatur-Rendering
-   - Generator/Validator-Kohärenz
-   - Architektur- und Determinismus-Constraints
-
-## Auswirkungen
-
-- Deutlich tiefere, strukturierte API-Doku in `docs/modules/`:
-  - Funktions- und Methoden-Parameter, Rückgabetypen
-  - Interface-Eigenschaften inkl. Optionalität
-- Reduktion von Signatur-Abweichungs-Warnungen, die nur auf
-  Formatierungsunterschieden beruhten.
-- Klare Trennung zwischen:
-  - zentraler Signaturlogik (`core/signature-formatter`)
-  - Rendering (Generator)
-  - Validierung (Validator)
-
-Für interne Infrastruktur kann die Strenge über
-`SignatureMatchingOptions` reduziert werden, während öffentliche APIs
-mit voller Tiefe validiert werden.
-
-## Alternativen
-
-- Belassen der getrennten Formatierungslogik in Generator und Validator:
-  - verworfen wegen hoher Wartungskosten und Fehleranfälligkeit.
-- Nur oberflächliche Doku (Namen, keine Typen) akzeptieren:
-  - verworfen, da sie dem Produktanspruch von Noyrax als
-    API-orientiertes Doku-System widerspricht.
-
-