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

package/docs/system/SYSTEM_ANALYSIS.md

@@ -1,947 +0,0 @@
-# Systemanalyse: Noyrax Documentation System Plugin
-
-**Stand:** 2025-01-XX  
-**Zweck:** Umfassende Systemanalyse mit Funktionen, Ablaufdiagrammen, Sequenzdiagrammen, Vorteilen und Auswirkungen
-
----
-
-## Inhaltsverzeichnis
-
-1. [System-Übersicht und Architektur](#1-system-übersicht-und-architektur)
-2. [Funktionsübersicht](#2-funktionsübersicht)
-3. [Ablaufdiagramme](#3-ablaufdiagramme)
-4. [Sequenzdiagramme](#4-sequenzdiagramme)
-5. [Vorteile gegenüber anderen Systemen](#5-vorteile-gegenüber-anderen-systemen)
-6. [Auswirkungen](#6-auswirkungen)
-
----
-
-## 1. System-Übersicht und Architektur
-
-### 1.1 Architektur-Übersicht
-
-Noyrax ist eine **VS Code Extension** zur automatischen Dokumentationsgenerierung mit Selbst-Validierung und Drift-Detection. Das System besteht aus mehreren Schichten:
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                    VS Code Extension                        │
-│                  (src/extension.ts)                         │
-├─────────────────────────────────────────────────────────────┤
-│                                                             │
-│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
-│  │   Scanner    │  │  Generator   │  │  Validator   │      │
-│  │              │  │              │  │              │      │
-│  │  - File I/O  │  │  - Markdown  │  │  - Drift     │      │
-│  │  - Git Diff  │  │  - Templates │  │  - Coverage  │      │
-│  │  - Parsers   │  │  - Index     │  │  - Reports   │      │
-│  └──────────────┘  └──────────────┘  └──────────────┘      │
-│         │                 │                 │               │
-│         └─────────────────┼─────────────────┘               │
-│                           │                                 │
-│                    ┌──────────────┐                         │
-│                    │    Cache     │                         │
-│                    │  - AST       │                         │
-│                    │  - Signatures│                         │
-│                    │  - Output    │                         │
-│                    │  - Dependencies│                       │
-│                    └──────────────┘                         │
-│                           │                                 │
-│                    ┌──────────────┐                         │
-│                    │     Core     │                         │
-│                    │  - Signature │                         │
-│                    │    Formatter │                         │
-│                    │  - Symbol    │                         │
-│                    │    Classifier│                         │
-│                    │  - Symbols   │                         │
-│                    │  - Git       │                         │
-│                    │  - Scanner   │                         │
-│                    └──────────────┘                         │
-│                                                             │
-├─────────────────────────────────────────────────────────────┤
-│  Integrations:  VS Code │ CLI │ MCP Server │ GitHub Action │
-└─────────────────────────────────────────────────────────────┘
-```
-
-### 1.2 Modul-Struktur
-
-Das System ist in folgende Module unterteilt:
-
-#### Core-Module (`src/core/`)
-
-- **`scanner.ts`** - Workspace-Scanning mit Git-Diff-Unterstützung
-- **`signature-formatter.ts`** (ADR-020) - Zentrale Signatur-Formatierung für Generator und Validator
-- **`symbol-classifier.ts`** (ADR-021) - Semantische Klassifizierung von Symbolen (visibility, role, priority)
-- **`symbols.ts`** - Symbol-Hashing und -Vergleich
-- **`git.ts`** - Git-Integration für inkrementelle Updates
-- **`async.ts`** - Async-Hilfsfunktionen (mapLimit)
-- **`consolidation.ts`** - Union-Bildung für Symbole und Dependencies
-
-#### Parser-Module (`src/parsers/`)
-
-- **`ts-js.ts`** - TypeScript/JavaScript-Parser mit ts-morph
-- **`python.ts`** - Python-Parser mit tree-sitter
-- **`json-yaml.ts`** - JSON/YAML/Markdown-Parser
-- **`dependencies.ts`** - Dependency-Extraktion (TypeScript/JavaScript, Python)
-- **`types.ts`** - Gemeinsame Typen (ParsedSymbol, SymbolSignature, etc.)
-
-#### Generator-Module (`src/generator/`)
-
-- **`index.ts`** - Haupt-Generierungsfunktion (`generatePerFileDocs`)
-- **`module-doc.ts`** - Modul-Dokumentation-Rendering mit SignatureFormatter, SymbolClassifier und semantischem Rendering (ADR-022)
-- **`adr-linker.ts`** (ADR-023) - Automatische ADR-Verknüpfung mit Modulen
-- **`dependency-graph.ts`** - Dependency-Graph-Generierung (Mermaid)
-- **`change-report.ts`** - Change Report-Generierung (Zeit-Dimension)
-
-#### Validator-Module (`src/validator/`)
-
-- **`index.ts`** - Haupt-Validierungsfunktionen (`validateSymbols`, `validateMarkdownDir`, `computeCoverage`)
-- **`signature-matching.ts`** - Signatur-Matching mit SignatureFormatter und SymbolClassifier
-- **`status.ts`** - Status-Klassifizierung (grün/gelb/rot)
-
-#### Cache-Module (`src/cache/`)
-
-- **`ast-cache.ts`** - AST-Hash-Cache für inkrementelle Updates
-- **`signature-cache.ts`** - Signatur-Cache für Drift-Detection
-- **`output-cache.ts`** - Output-Hash-Cache für Content-Hashing
-- **`dependencies-cache.ts`** - Dependencies-Cache für Union-Bildung
-
-#### Weitere Module
-
-- **`drift/index.ts`** - Drift-Detection (`detectDrift`, `computeCacheEntries`)
-- **`index/index.ts`** - Symbol-Index-Generierung (`buildIndexFromSymbols`, `writeJsonlIndex`)
-- **`cli/`** (ADR-025) - CLI-Tools (`scan-cli.ts`, `validate-cli.ts`) für MCP-Server-Bridge
-- **`mcp/`** - MCP-Server-Integration mit Tools und Resources
-
-### 1.3 Mehrdimensionaler Navigationsraum (ADR-024)
-
-Das System generiert ein **Koordinaten-System** mit 5 Dimensionen, das KI-Agenten ermöglicht, sich im Code-Raum zu bewegen:
-
-| Dimension | Artefakt | Funktion | Zugriff |
-|-----------|----------|----------|---------|
-| **Modul-Raum (X)** | `docs/modules/*.md` | API-Dokumentation pro Datei | `docs://modules/{path}` |
-| **Symbol-Raum (Y)** | `docs/index/symbols.jsonl` | Symbole mit Dependencies | `docs://index/symbols.jsonl` |
-| **Beziehungs-Raum (Z)** | `docs/system/DEPENDENCY_GRAPH.md` | Modul-Abhängigkeiten | `docs://system/graph` |
-| **Wissens-Raum (W)** | `docs/adr/*.md` | Architektur-Entscheidungen (Landkarte) | `docs://adr/{name}` |
-| **Zeit-Raum (T)** | `docs/system/CHANGE_REPORT.md` | Änderungen über die Zeit | `docs://system/changes` |
-
-**MCP-Server-Integration:**
-- 99 Resources verfügbar (4 System, 71 Module, 24 ADRs)
-- Strukturierter Zugriff via `docs://` URIs
-- Tools: `validation/runScan`, `validation/runValidate`, `validation/runDriftCheck`, `validation/analyzeImpact`
-
-### 1.4 Plugin-Ecosystem Integration
-
-Noyrax ist Teil eines modularen Plugin-Ecosystems:
-
-```
-Documentation-System-Plugin (Basis)
-    ↓ generiert docs/
-Database Plugin ✅ KOMPLETT
-    ↓ persistiert in SQLite
-Semantic Brain Plugin 🔄 FAST FERTIG
-    ↓ Graph & Embeddings
-Context/RAG Plugin 📋 GEPLANT
-    ↓ AI-Agent Integration
-```
-
-**Database Plugin:**
-- Liest `docs/modules/*.md`, `docs/index/symbols.jsonl`, `docs/system/DEPENDENCIES.md`
-- Persistiert in SQLite für schnelle Abfragen
-- 33 ADRs dokumentieren die Implementierung
-
-**Semantic Brain Plugin:**
-- Transformiert Rohdaten in semantische Strukturen (Graph, Embeddings)
-- Graph-Layer: Nodes, Edges, Communities
-- Vector-Layer: Embeddings, Similarity-Scores
-- APIs noch nicht vollständig implementiert
-
-**Context/RAG Plugin:**
-- Geplant für AI-Agent-Integration
-- Nutzt semantische Daten vom Semantic Brain Plugin
-- Multi-Provider RAG (OpenAI, Anthropic, lokale Modelle)
-
----
-
-## 2. Funktionsübersicht
-
-### 2.1 Core-Komponenten
-
-#### SignatureFormatter (ADR-020)
-
-**Datei:** `src/core/signature-formatter.ts`
-
-**Funktionen:**
-- `formatForDoc(symbol: ParsedSymbol): string` - Formatiert ein Symbol für die Dokumentation (verwendet von Generator und Validator)
-- `compare(expected: string, documented: string, options?: CompareOptions): CompareResult` - Vergleicht zwei Signaturen mit konfigurierbarer Toleranz
-- `normalize(signature: string): string` - Normalisiert eine Signatur für Vergleiche (Whitespace, Formatierung)
-- `normalizeSignature(sig: SymbolSignature): string` - Normalisiert eine SymbolSignature zu einem String für Hashing/Vergleiche
-
-**Verwendung:**
-- Generator (`module-doc.ts`): Rendert Signaturen konsistent
-- Validator (`signature-matching.ts`): Vergleicht erwartete vs. dokumentierte Signaturen
-- Toleranzen: Optionale Felder (`field` vs `field?`), Generics-Vereinfachungen (`T[]` vs `{}`)
-
-#### SymbolClassifier (ADR-021)
-
-**Datei:** `src/core/symbol-classifier.ts`
-
-**Funktion:**
-- `classifySymbol(symbol: ParsedSymbol): SymbolClassification` - Klassifiziert ein Symbol semantisch
-
-**Rückgabe:**
-- `visibility: 'public' | 'internal'` - Sichtbarkeit des Symbols
-- `role: 'service-api' | 'domain-model' | 'config' | 'infra' | 'other'` - Semantische Rolle
-- `priority: 'high' | 'normal' | 'low'` - Priorität für Doku/Validierung
-
-**Heuristiken:**
-- Service-API: Funktionen/Klassen mit Suffixen `Api`, `Service`, `Manager`, `Controller`
-- Domain-Model: Interfaces/Klassen mit Suffixen `Entity`, `Model`, `Record`, `Request`, `Response`
-- Config: Typen mit Suffixen `Config`, `Options`, `Settings`
-- Infra: Typen mit Substrings `Cache`, `Validator`, `Repository`, `Migration`, `Snapshot`
-
-**Verwendung:**
-- Generator: Rollenbasierte Doku-Tiefe (Public-APIs tiefer dokumentiert)
-- Validator: Prioritäts-basierte Validierung (wichtige APIs strenger geprüft)
-
-#### AdrLinker (ADR-023)
-
-**Datei:** `src/generator/adr-linker.ts`
-
-**Klasse:** `AdrLinker`
-
-**Methoden:**
-- `getRelevantAdrs(filePath: string): string[]` - Gibt relevante ADR-Nummern für einen Dateipfad zurück
-- `getAdrMetadata(adrNumber: string): AdrMetadata | undefined` - Gibt ADR-Metadaten (Nummer, Titel, Dateiname) zurück
-- `getAllAdrMappings(): Map<string, string[]>` - Gibt alle Dateipfad-zu-ADR-Mappings zurück
-
-**Funktionalität:**
-- Parst alle ADR-Dateien aus `docs/adr/*.md`
-- Extrahiert automatisch Dateipfade aus ADR-Inhalten (Pattern: `` `src/...` ``, `Datei: src/...`, etc.)
-- Unterstützt optionale Metadata-Datei (`docs/adr-metadata.json`) für manuelle Overrides und Excludes
-- Cacht ADR-Metadaten für effiziente Lookups
-
-**Integration:**
-- `module-doc.ts` fügt automatisch "Relevante ADRs"-Abschnitt am Anfang jeder Modul-Doku ein
-
-### 2.2 Scan-Funktionen
-
-**Datei:** `src/core/scanner.ts`
-
-**Funktion:**
-- `scanWorkspace(options: ScanOptions, includeBackups: boolean): ScannedFile[]` - Scannt Workspace nach relevanten Dateien
-
-**Features:**
-- Language-Detection: TypeScript, JavaScript, Python, JSON/YAML, Markdown
-- File-Filtering: Backups, node_modules, etc. (konfigurierbar)
-- Git-Diff-Unterstützung: Nur geänderte Dateien scannen (inkrementeller Modus)
-- Repository-relative Pfade für konsistente Pfad-Handhabung
-
-### 2.3 Parse-Funktionen
-
-#### TsJsParser
-
-**Datei:** `src/parsers/ts-js.ts`
-
-**Funktionalität:**
-- Parst TypeScript/JavaScript mit ts-morph
-- Extrahiert: Klassen, Interfaces, Funktionen, Methoden, Variablen, Types, Enums
-- Dependency-Extraktion: `extractTsJsDependencies(sourceFile, filePath)` - Extrahiert Import-Abhängigkeiten
-
-#### PythonParser
-
-**Datei:** `src/parsers/python.ts`
-
-**Funktionalität:**
-- Parst Python mit tree-sitter
-- Extrahiert: Klassen, Funktionen, Variablen
-- Dependency-Extraktion: `extractPythonDependencies(content, filePath)` - Extrahiert Import-Abhängigkeiten
-
-#### JsonYamlParser
-
-**Datei:** `src/parsers/json-yaml.ts`
-
-**Funktionalität:**
-- Parst JSON/YAML/Markdown
-- Extrahiert: Schema-Strukturen, Frontmatter
-
-### 2.4 Generierungs-Funktionen
-
-**Datei:** `src/generator/index.ts`
-
-**Funktion:**
-- `generatePerFileDocs(symbols: ParsedSymbol[], outDir: string, existingDocs: Map<string, string>): Map<string, string>` - Generiert Modul-Dokumentation für alle Dateien
-
-**Datei:** `src/generator/module-doc.ts`
-
-**Funktion:**
-- `renderModuleDoc(doc: ModuleDoc, filePath: string, adrDir?: string): string` - Rendert Modul-Dokumentation mit:
-  - SignatureFormatter für konsistente Signatur-Darstellung
-  - SymbolClassifier für rollenbasierte Doku-Tiefe
-  - AdrLinker für ADR-Verknüpfung
-  - Semantisches Rendering (ADR-022): Klassen mit Beschreibung, Konstanten strukturiert, Parameter-Tabellen
-
-**Datei:** `src/generator/dependency-graph.ts`
-
-**Funktionen:**
-- `generateMermaidGraph(dependencies: ModuleDependency[]): string` - Generiert Mermaid-Graph (127 Knoten)
-- `generateDependencyOverview(dependencies: ModuleDependency[]): string` - Generiert Dependency-Übersicht
-
-**Datei:** `src/generator/change-report.ts`
-
-**Funktion:**
-- `generateChangeReport(changes: ChangeReportData): string` - Generiert Change Report (Zeit-Dimension)
-
-**Datei:** `src/index/index.ts`
-
-**Funktionen:**
-- `buildIndexFromSymbols(symbols: ParsedSymbol[], dependencies: ModuleDependency[]): IndexRow[]` - Baut Symbol-Index mit Dependencies
-- `writeJsonlIndex(rows: IndexRow[], indexPath: string): void` - Schreibt JSONL-Index (445 Zeilen)
-
-### 2.5 Validierungs-Funktionen
-
-**Datei:** `src/validator/index.ts`
-
-**Funktionen:**
-- `validateSymbols(symbols: ParsedSymbol[]): ValidationReport` - Validiert Symbole
-- `validateMarkdownDir(modulesDir: string, symbols: ParsedSymbol[]): MarkdownDirReport` - Validiert Markdown-Dokumentation
-- `computeCoverage(symbols: ParsedSymbol[], modulesDir: string, thresholds: CoverageThresholds): CoverageReport` - Berechnet Coverage-Metriken
-
-**Datei:** `src/validator/signature-matching.ts`
-
-**Funktion:**
-- `validateSignatureMatching(symbols: ParsedSymbol[], modulesDir: string, options?: SignatureMatchingOptions): SignatureMismatch[]` - Validiert Signatur-Matching mit:
-  - SignatureFormatter für erwartete Signatur
-  - SymbolClassifier für rollenbasierte Validierung (Public-APIs strenger)
-
-**Datei:** `src/validator/status.ts`
-
-**Funktion:**
-- `computeValidationStatus(errors: string[], warnings: string[], ...): StatusReport` - Klassifiziert Status (grün/gelb/rot)
-
-### 2.6 Cache-Funktionen
-
-#### AST-Cache
-
-**Datei:** `src/cache/ast-cache.ts`
-
-**Funktionen:**
-- `loadAstHashCache(filePath: string): AstHashCache | null` - Lädt AST-Hash-Cache
-- `saveAstHashCache(cacheDir: string, cache: AstHashCache): void` - Speichert AST-Hash-Cache
-- `computeFileHash(content: string): string` - Berechnet Datei-Hash
-
-**Zweck:** Inkrementelle Updates (nur geänderte Dateien parsen)
-
-#### Signature-Cache
-
-**Datei:** `src/cache/signature-cache.ts`
-
-**Funktionen:**
-- `loadSignatureCache(filePath: string): SignatureCache | null` - Lädt Signatur-Cache
-- `saveSignatureCache(cacheDir: string, cache: SignatureCache): void` - Speichert Signatur-Cache
-
-**Zweck:** Drift-Detection (Signatur-Änderungen erkennen)
-
-#### Output-Cache
-
-**Datei:** `src/cache/output-cache.ts`
-
-**Funktionen:**
-- `loadOutputHashCache(filePath: string): OutputHashCache | null` - Lädt Output-Hash-Cache
-- `saveOutputHashCache(cacheDir: string, cache: OutputHashCache): void` - Speichert Output-Hash-Cache
-- `computeContentHash(content: string): string` - Berechnet Content-Hash
-
-**Zweck:** Content-Hashing (nur geänderte Dokumentation schreiben)
-
-#### Dependencies-Cache
-
-**Datei:** `src/cache/dependencies-cache.ts`
-
-**Funktionen:**
-- `loadDependenciesCache(filePath: string): DependenciesCache | null` - Lädt Dependencies-Cache
-- `saveDependenciesCache(cacheDir: string, cache: DependenciesCache): void` - Speichert Dependencies-Cache
-
-**Zweck:** Union-Bildung (Dependencies aus geparsten und gecachten Dateien mergen)
-
-### 2.7 Drift-Detection
-
-**Datei:** `src/drift/index.ts`
-
-**Funktionen:**
-- `detectDrift(prev: SignatureCache, current: SignatureCacheEntry[]): DriftResult` - Erkennt Signatur-Abweichungen
-- `computeCacheEntries(symbols: ParsedSymbol[]): SignatureCacheEntry[]` - Berechnet Cache-Einträge
-
-**Zweck:** Automatische Erkennung von Code-Dokumentation-Abweichungen
-
-### 2.8 MCP-Server Tools (ADR-025)
-
-**Dateien:** `mcp/src/tools/`
-
-**Tools:**
-- `scan.ts` - `validation/runScan` - Scan via CLI-Bridge (`npm run scan:cli`)
-- `validate.ts` - `validation/runValidate` - Validate via CLI-Bridge (`npm run validate:cli`)
-- `drift.ts` - `validation/runDriftCheck` - Drift-Check
-- `impact.ts` - `validation/analyzeImpact` - Impact-Analyse via Symbol-Index
-
-**Resources:** `mcp/src/server.ts`
-- `docs://modules/{path}` - Modul-Dokumentation (71 Resources)
-- `docs://system/graph` - Dependency-Graph
-- `docs://system/dependencies` - Dependency-Übersicht
-- `docs://system/changes` - Change Report
-- `docs://adr/{name}` - ADRs (24 Resources)
-- `docs://index/symbols.jsonl` - Symbol-Index
-
-**Gesamt:** 99 Resources verfügbar
-
-### 2.9 Verification-Scripts (ADR-026)
-
-**Dateien:** `scripts/`
-
-**Scripts:**
-- `verify-architecture.js` - Architektur-Regeln prüfen (Imports, Zyklen)
-- `verify-adrs.js` - ADR-Claims gegen Code prüfen (Dateien, Funktionen)
-- `verify-imports.js` - Import-Verfügbarkeit prüfen (Exports, Pfade)
-
-**Integration:**
-- Pre-Commit Hook (`.husky/pre-commit`)
-- GitHub Actions (`.github/workflows/verification.yml`)
-- VS Code Tasks (`.vscode/tasks.json`)
-- npm Scripts: `verify:all`, `verify:architecture`, `verify:adrs`, `verify:imports`
-
----
-
-## 3. Ablaufdiagramme
-
-### 3.1 Haupt-Workflow: Scan → Generate → Validate
-
-```mermaid
-flowchart TD
-    Start([Benutzer startet Generate]) --> Config[Config laden<br/>Workspace-Root, Output-Path,<br/>apiDoc.depth, apiDoc.includeInternal]
-    Config --> Scan[Scan Workspace<br/>scanWorkspace]
-    
-    Scan --> GitCheck{Git-Diff<br/>aktiviert?}
-    GitCheck -->|Ja| GitDiff[Git-Diff<br/>getChangedFiles]
-    GitCheck -->|Nein| FullScan[Vollscan]
-    GitDiff --> ChangedFiles{Geänderte<br/>Dateien<br/>gefunden?}
-    ChangedFiles -->|Ja| FilteredScan[Gefilterter Scan]
-    ChangedFiles -->|Nein| FullScan
-    FilteredScan --> Parse
-    FullScan --> Parse
-    
-    Parse[Parse Dateien<br/>TsJsParser, PythonParser,<br/>JsonYamlParser] --> Union[Union-Bildung<br/>buildSymbolsUnion,<br/>buildDependenciesUnion]
-    
-    Union --> Generate[Generate Docs<br/>generatePerFileDocs]
-    
-    Generate --> SigFormat[SignatureFormatter<br/>formatForDoc]
-    SigFormat --> SymClass[SymbolClassifier<br/>classifySymbol]
-    SymClass --> ADRLink[AdrLinker<br/>getRelevantAdrs]
-    ADRLink --> Render[Render Module-Doc<br/>renderModuleDoc<br/>semantisches Rendering]
-    
-    Render --> CacheUpdate[Cache-Update<br/>AST, Signature, Output,<br/>Dependencies]
-    CacheUpdate --> Index[Index schreiben<br/>buildIndexFromSymbols,<br/>writeJsonlIndex]
-    Index --> Graph[Graph generieren<br/>generateMermaidGraph,<br/>generateDependencyOverview]
-    Graph --> Report[Change Report<br/>generateChangeReport]
-    Report --> Validate[Validate<br/>validateSymbols,<br/>validateMarkdownDir]
-    
-    Validate --> SigMatch[Signature Matching<br/>SignatureFormatter +<br/>SymbolClassifier]
-    SigMatch --> Coverage[Coverage<br/>computeCoverage]
-    Coverage --> Status[Status<br/>computeValidationStatus]
-    Status --> End([Fertig])
-    
-    style SigFormat fill:#e1f5ff
-    style SymClass fill:#e1f5ff
-    style ADRLink fill:#e1f5ff
-    style Render fill:#e1f5ff
-    style SigMatch fill:#fff4e1
-```
-
-**Entscheidungspunkte:**
-- Git-Diff aktiviert? → Inkrementeller Modus vs. Vollscan
-- Erster Lauf? → Cache vorhanden? → Vollscan erforderlich
-- Symbol-Rolle/Priorität? → Rollenbasierte Doku-Tiefe und Validierung
-
-**Phasen:**
-1. **Scan:** Workspace-Scan mit Git-Diff-Option
-2. **Parse:** Multi-Language-Parsing (TypeScript, Python, JSON/YAML)
-3. **Union:** Symbole und Dependencies aus geparsten und gecachten Dateien mergen
-4. **Generate:** Modul-Dokumentation mit SignatureFormatter, SymbolClassifier, AdrLinker
-5. **Cache:** AST, Signature, Output, Dependencies aktualisieren
-6. **Index:** Symbol-Index mit Dependencies schreiben
-7. **Graph:** Dependency-Graph und -Übersicht generieren
-8. **Report:** Change Report generieren (Zeit-Dimension)
-9. **Validate:** Validierung mit SignatureFormatter und SymbolClassifier
-
----
-
-## 4. Sequenzdiagramme
-
-### 4.1 Scan-Flow
-
-```mermaid
-sequenceDiagram
-    autonumber
-    participant User as Benutzer
-    participant Ext as Extension
-    participant Scanner as Scanner<br/>(core/scanner.ts)
-    participant Git as Git<br/>(core/git.ts)
-    participant LangDetect as Language Detection
-    
-    User->>Ext: Startet Scan/Generate
-    Ext->>Scanner: scanWorkspace(options, includeBackups)
-    
-    Scanner->>Scanner: Workspace durchsuchen
-    Scanner->>LangDetect: Language erkennen
-    LangDetect-->>Scanner: Language (ts/js/python/json/yaml)
-    
-    alt Git-Diff aktiviert
-        Scanner->>Git: getChangedFiles(workspaceRoot)
-        Git-->>Scanner: Set<string> geänderte Dateien
-        Scanner->>Scanner: Dateien filtern
-    end
-    
-    Scanner-->>Ext: ScannedFile[] (mit Language)
-    Ext->>Ext: Dateien für Parsing vorbereiten
-```
-
-### 4.2 Generate-Flow (mit neuen Features)
-
-```mermaid
-sequenceDiagram
-    autonumber
-    participant Ext as Extension
-    participant Scanner as Scanner
-    participant Parser as Parser<br/>(TsJsParser, PythonParser, etc.)
-    participant Generator as Generator<br/>(generator/index.ts)
-    participant SigFormat as SignatureFormatter<br/>(core/signature-formatter.ts)
-    participant SymClass as SymbolClassifier<br/>(core/symbol-classifier.ts)
-    participant ADRLink as AdrLinker<br/>(generator/adr-linker.ts)
-    participant ModuleDoc as Module-Doc<br/>(generator/module-doc.ts)
-    participant Cache as Cache<br/>(AST, Signature, Output, Dependencies)
-    participant Index as Index<br/>(index/index.ts)
-    
-    Ext->>Scanner: scanWorkspace()
-    Scanner-->>Ext: ScannedFile[]
-    
-    loop Für jede Datei
-        Ext->>Parser: parse(filePath, content)
-        Parser-->>Ext: ParsedSymbol[], ModuleDependency[]
-    end
-    
-    Ext->>Generator: generatePerFileDocs(symbols, outDir, existingDocs)
-    
-    loop Für jede Datei
-        Generator->>SigFormat: formatForDoc(symbol)
-        SigFormat-->>Generator: string (formatierte Signatur)
-        
-        Generator->>SymClass: classifySymbol(symbol)
-        SymClass-->>Generator: SymbolClassification<br/>(visibility, role, priority)
-        
-        Generator->>ADRLink: getRelevantAdrs(filePath)
-        ADRLink-->>Generator: string[] (ADR-Nummern)
-        
-        Generator->>ModuleDoc: renderModuleDoc(doc, filePath, adrDir)
-        Note over ModuleDoc: Semantisches Rendering:<br/>- Klassen mit Beschreibung<br/>- Konstanten strukturiert<br/>- Parameter-Tabellen
-        ModuleDoc-->>Generator: string (Markdown)
-    end
-    
-    Generator-->>Ext: Map<string, string> (Dateipfad → Markdown)
-    
-    Ext->>Cache: saveAstHashCache(), saveSignatureCache(),<br/>saveOutputHashCache(), saveDependenciesCache()
-    
-    Ext->>Index: buildIndexFromSymbols(symbols, dependencies)
-    Index-->>Ext: IndexRow[]
-    Ext->>Index: writeJsonlIndex(rows, indexPath)
-```
-
-### 4.3 Validate-Flow (mit neuen Features)
-
-```mermaid
-sequenceDiagram
-    autonumber
-    participant Ext as Extension
-    participant Scanner as Scanner
-    participant Parser as Parser
-    participant Validator as Validator<br/>(validator/index.ts)
-    participant SigMatch as Signature Matching<br/>(validator/signature-matching.ts)
-    participant SigFormat as SignatureFormatter
-    participant SymClass as SymbolClassifier
-    participant ModDocParser as Module-Doc Parser<br/>(generator/module-doc.ts)
-    participant Status as Status Reporter<br/>(validator/status.ts)
-    
-    Ext->>Scanner: scanWorkspace()
-    Scanner-->>Ext: ScannedFile[]
-    
-    loop Für jede Datei
-        Ext->>Parser: parse(filePath, content)
-        Parser-->>Ext: ParsedSymbol[]
-    end
-    
-    Ext->>Validator: validateSymbols(symbols)
-    Validator-->>Ext: ValidationReport
-    
-    Ext->>Validator: validateMarkdownDir(modulesDir, symbols)
-    
-    loop Für jede Modul-Doku
-        Validator->>ModDocParser: parseModuleDoc(content)
-        ModDocParser-->>Validator: ParsedModuleDoc
-    end
-    
-    Ext->>SigMatch: validateSignatureMatching(symbols, modulesDir)
-    
-    loop Für jedes Symbol
-        SigMatch->>SigFormat: formatForDoc(symbol)
-        SigFormat-->>SigMatch: string (erwartete Signatur)
-        
-        SigMatch->>ModDocParser: parseSignatureFromCode(code, kind)
-        ModDocParser-->>SigMatch: SymbolSignature
-        
-        SigMatch->>SymClass: classifySymbol(symbol)
-        SymClass-->>SigMatch: SymbolClassification<br/>(visibility, role, priority)
-        
-        SigMatch->>SigFormat: compare(expected, documented, options)
-        Note over SigMatch: Rollenbasierte Validierung:<br/>- Public-APIs: severity 'error'<br/>- Infra: severity 'warning'
-        SigFormat-->>SigMatch: CompareResult
-        
-        alt Signatur stimmt nicht überein
-            SigMatch->>SigMatch: Erstelle SignatureMismatch
-        end
-    end
-    
-    SigMatch-->>Ext: SignatureMismatch[]
-    
-    Ext->>Validator: computeCoverage(symbols, modulesDir, thresholds)
-    Validator-->>Ext: CoverageReport
-    
-    Ext->>Status: computeValidationStatus(errors, warnings, ...)
-    Status-->>Ext: StatusReport (grün/gelb/rot)
-```
-
-### 4.4 Drift-Detection-Flow
-
-```mermaid
-sequenceDiagram
-    autonumber
-    participant Ext as Extension
-    participant Scanner as Scanner
-    participant Parser as Parser
-    participant Drift as Drift Detector<br/>(drift/index.ts)
-    participant SigFormat as SignatureFormatter
-    participant SigCache as Signature Cache<br/>(cache/signature-cache.ts)
-    
-    Ext->>SigCache: loadSignatureCache(cachePath)
-    SigCache-->>Ext: SignatureCache | null
-    
-    Ext->>Scanner: scanWorkspace()
-    Scanner-->>Ext: ScannedFile[]
-    
-    loop Für jede Datei
-        Ext->>Parser: parse(filePath, content)
-        Parser-->>Ext: ParsedSymbol[]
-    end
-    
-    Ext->>Drift: computeCacheEntries(symbols)
-    
-    loop Für jedes Symbol
-        Drift->>SigFormat: normalizeSignature(symbol.signature)
-        SigFormat-->>Drift: string (normalisierte Signatur)
-    end
-    
-    Drift-->>Ext: SignatureCacheEntry[]
-    
-    Ext->>Drift: detectDrift(prev, current)
-    
-    loop Für jeden Cache-Eintrag
-        Drift->>Drift: Hash vergleichen
-        alt Hash unterschiedlich
-            Drift->>Drift: Als stale markieren
-        end
-    end
-    
-    Drift-->>Ext: DriftResult<br/>(staleSymbols: string[])
-    
-    alt Drift erkannt
-        Ext->>Ext: Warnung anzeigen
-    end
-```
-
-### 4.5 ADR-Linking-Flow
-
-```mermaid
-sequenceDiagram
-    autonumber
-    participant Generator as Generator<br/>(generator/index.ts)
-    participant ModuleDoc as Module-Doc<br/>(generator/module-doc.ts)
-    participant ADRLink as AdrLinker<br/>(generator/adr-linker.ts)
-    participant FS as File System
-    
-    Generator->>ModuleDoc: renderModuleDoc(doc, filePath, adrDir)
-    
-    alt ADR-Dir angegeben
-        ModuleDoc->>ADRLink: new AdrLinker(adrDir, metadataPath)
-        
-        ADRLink->>FS: readdirSync(adrDir)
-        FS-->>ADRLink: string[] (ADR-Dateien)
-        
-        loop Für jede ADR-Datei
-            ADRLink->>FS: readFileSync(adrPath, 'utf8')
-            FS-->>ADRLink: string (ADR-Inhalt)
-            
-            ADRLink->>ADRLink: parseAdrFile(adrPath)
-            Note over ADRLink: Extrahiert:<br/>- ADR-Nummer aus Dateiname<br/>- Titel aus erster Zeile<br/>- Dateipfade aus Inhalt<br/>(Pattern: `src/...`, Datei: src/..., etc.)
-            ADRLink->>ADRLink: Mapping erstellen<br/>(filePath → ADR-Nummern[])
-        end
-        
-        alt Metadata-Datei vorhanden
-            ADRLink->>FS: readFileSync(metadataPath, 'utf8')
-            FS-->>ADRLink: string (JSON)
-            ADRLink->>ADRLink: loadMetadataOverrides(metadataPath)
-            Note over ADRLink: Lädt Overrides und Excludes
-        end
-        
-        ModuleDoc->>ADRLink: getRelevantAdrs(filePath)
-        ADRLink-->>ModuleDoc: string[] (ADR-Nummern, sortiert)
-        
-        ModuleDoc->>ADRLink: getAdrMetadata(adrNumber)
-        loop Für jede ADR-Nummer
-            ADRLink-->>ModuleDoc: AdrMetadata (Nummer, Titel, Dateiname)
-        end
-        
-        ModuleDoc->>ModuleDoc: "Relevante ADRs"-Abschnitt generieren
-        Note over ModuleDoc: Format:<br/>## Relevante ADRs<br/>- [ADR-020: Titel](../adr/020-...md)
-    end
-    
-    ModuleDoc-->>Generator: string (Markdown mit ADR-Links)
-```
-
-### 4.6 MCP-Server Flow
-
-```mermaid
-sequenceDiagram
-    autonumber
-    participant Client as MCP-Client<br/>(Cursor, etc.)
-    participant MCPServer as MCP-Server<br/>(mcp/src/server.ts)
-    participant Tool as MCP-Tool<br/>(mcp/src/tools/scan.ts)
-    participant NPM as npm Script
-    participant CLITool as CLI-Tool<br/>(src/cli/scan-cli.ts)
-    participant Core as Core Functions<br/>(scanner, parser, etc.)
-    
-    Client->>MCPServer: callTool('validation/runScan', { workspaceRoot, ... })
-    
-    MCPServer->>Tool: runScan(request)
-    
-    Tool->>NPM: exec('npm run scan:cli', { cwd: workspaceRoot })
-    NPM->>CLITool: node out/cli/scan-cli.js
-    
-    CLITool->>Core: scanWorkspace(options)
-    Core-->>CLITool: ScannedFile[]
-    
-    CLITool->>Core: Parser.parse(...)
-    Core-->>CLITool: ParsedSymbol[]
-    
-    CLITool->>CLITool: JSON.stringify(result)
-    CLITool-->>NPM: JSON-Output (stdout)
-    NPM-->>Tool: JSON-String
-    
-    Tool->>Tool: JSON.parse(output)
-    Tool-->>MCPServer: ScanResponse (strukturiert)
-    MCPServer-->>Client: ScanResponse
-    
-    Note over Client,MCPServer: Gleiches Pattern für:<br/>- validation/runValidate<br/>- validation/runDriftCheck<br/>- validation/analyzeImpact
-```
-
----
-
-## 5. Vorteile gegenüber anderen Systemen
-
-### 5.1 Vergleichs-Tabelle
-
-| Feature | Noyrax | TypeDoc/JSDoc | Doxygen | Sphinx | JSDoc |
-|---------|--------|---------------|---------|--------|-------|
-| **Automatische Generierung** | ✅ Vollautomatisch | ❌ Manuell | ⚠️ Teilweise | ⚠️ Teilweise | ❌ Manuell |
-| **Drift-Detection** | ✅ Automatisch | ❌ Keine | ❌ Keine | ❌ Keine | ❌ Keine |
-| **Signatur-Validierung** | ✅ Mit Toleranzen | ❌ Keine | ⚠️ Basis | ❌ Keine | ❌ Keine |
-| **Multi-Language** | ✅ TS/JS/Python/JSON/YAML | ⚠️ Nur TS/JS | ⚠️ C++/Java | ⚠️ Nur Python | ⚠️ Nur JS |
-| **Inkrementelle Updates** | ✅ Git-Diff-basiert | ❌ Immer Vollscan | ❌ Immer Vollscan | ⚠️ Teilweise | ❌ Immer Vollscan |
-| **Deterministische Ausgabe** | ✅ Garantiert | ⚠️ Teilweise | ⚠️ Teilweise | ⚠️ Teilweise | ⚠️ Teilweise |
-| **Semantische Klassifizierung** | ✅ SymbolClassifier | ❌ Keine | ❌ Keine | ❌ Keine | ❌ Keine |
-| **Rollenbasierte Doku-Tiefe** | ✅ Public-APIs tiefer | ❌ Gleich für alle | ❌ Gleich für alle | ❌ Gleich für alle | ❌ Gleich für alle |
-| **ADR-Integration** | ✅ Automatisch | ❌ Keine | ❌ Keine | ❌ Keine | ❌ Keine |
-| **Mehrdimensionaler Raum** | ✅ 5 Dimensionen | ❌ Keine | ❌ Keine | ❌ Keine | ❌ Keine |
-| **MCP-Server** | ✅ 99 Resources | ❌ Keine | ❌ Keine | ❌ Keine | ❌ Keine |
-| **AI-Native** | ✅ Cursor Rules, Verification | ❌ Keine | ❌ Keine | ❌ Keine | ❌ Keine |
-| **Reality-Driven** | ✅ Verification-Loops | ❌ Keine | ❌ Keine | ❌ Keine | ❌ Keine |
-| **Impact-Analyse** | ✅ Via Symbol-Index | ❌ Keine | ❌ Keine | ❌ Keine | ❌ Keine |
-| **CI/CD-Integration** | ✅ GitHub Actions | ⚠️ Möglich | ⚠️ Möglich | ⚠️ Möglich | ⚠️ Möglich |
-
-### 5.2 Feature-Matrix: Semantische Features
-
-| Feature | Beschreibung | Vorteil |
-|---------|--------------|---------|
-| **SymbolClassifier** | Unterscheidet Service-API, Domain-Model, Config, Infra | Public-APIs werden tiefer dokumentiert, Infra weniger strikt validiert |
-| **Rollenbasierte Doku-Tiefe** | Doku-Tiefe abhängig von Symbol-Rolle | Wichtige APIs vollständig dokumentiert, Infra nicht überladen |
-| **Prioritäts-basierte Validierung** | Validierungsstrenge abhängig von Priorität | Fokus auf wichtige APIs, weniger Rauschen bei Infra |
-| **SignatureFormatter** | Zentrale Signatur-Formatierung | Konsistenz zwischen Generator und Validator |
-| **ADR-Verknüpfung** | Automatische Verknüpfung von ADRs mit Modulen | Architektur-Entscheidungen direkt im Code-Kontext |
-| **Mehrdimensionaler Raum** | 5 Dimensionen für Navigation | KI-Agenten können gezielt navigieren |
-| **Reality-Driven Development** | Verification-Loops verhindern Halluzinationen | Code als einzige Wahrheitsquelle |
-
-### 5.3 Vorteile im Detail
-
-#### 5.3.1 Automatische Generierung
-
-**Noyrax:**
-- Keine manuelle Wartung erforderlich
-- Deterministische Ausgabe (gleiche Eingabe → gleiche Ausgabe)
-- Inkrementelle Updates (nur geänderte Dateien)
-
-**Andere Systeme:**
-- Manuelle Dokumentation → veraltet sofort
-- Keine Validierung → Inkonsistenzen
-- Immer Vollscan → langsam bei großen Projekten
-
-#### 5.3.2 Drift-Detection
-
-**Noyrax:**
-- Automatische Erkennung von Code-Dokumentation-Abweichungen
-- Signatur-Validierung mit Toleranzen (optionale Felder, Generics)
-- Coverage-Metriken mit konfigurierbaren Thresholds
-
-**Andere Systeme:**
-- Keine Drift-Detection → Dokumentation kann veraltet sein ohne Warnung
-- Keine Signatur-Validierung → Inkonsistenzen werden nicht erkannt
-
-#### 5.3.3 Semantische Intelligenz
-
-**Noyrax:**
-- SymbolClassifier: Unterscheidung zwischen Service-API, Domain-Model, Config, Infra
-- Rollenbasierte Doku-Tiefe: Public-APIs werden tiefer dokumentiert
-- Prioritäts-basierte Validierung: Wichtige APIs strenger geprüft
-
-**Andere Systeme:**
-- Keine semantische Klassifizierung → alle Symbole gleich behandelt
-- Keine rollenbasierte Doku-Tiefe → Infra überladen, APIs unterdokumentiert
-
-#### 5.3.4 Mehrdimensionaler Navigationsraum
-
-**Noyrax:**
-- 5 Dimensionen: Modul-Raum, Symbol-Raum, Beziehungs-Raum, Wissens-Raum, Zeit-Raum
-- Koordinaten-System für AI-Agenten
-- MCP-Server: 99 Resources für strukturierten Zugriff
-
-**Andere Systeme:**
-- Keine mehrdimensionale Navigation → flache Dokumentationsstruktur
-- Keine MCP-Server-Integration → keine strukturierte Agent-Kommunikation
-
-#### 5.3.5 AI-Native
-
-**Noyrax:**
-- MCP-Server Integration für strukturierte Agent-Kommunikation
-- Cursor Rules für strukturierte Workflows
-- Reality-Driven Development: Verification-Loops verhindern Halluzinationen
-- Impact-Analyse via Symbol-Index
-
-**Andere Systeme:**
-- Keine AI-Integration → keine strukturierte Agent-Kommunikation
-- Keine Verification-Loops → Agenten können halluzinieren
-
----
-
-## 6. Auswirkungen
-
-### 6.1 Dokumentation
-
-#### Vorher (ohne Noyrax)
-
-- **Manuelle Wartung:** Entwickler müssen Dokumentation manuell pflegen → veraltet sofort
-- **Keine Validierung:** Inkonsistenzen zwischen Code und Dokumentation werden nicht erkannt
-- **Keine Struktur:** Dokumentation ist flach, schwer navigierbar
-- **Keine Semantik:** Alle Symbole gleich behandelt, keine Unterscheidung zwischen Public-APIs und Infra
-
-#### Nachher (mit Noyrax)
-
-- **Automatische Generierung:** Dokumentation wird automatisch aus Code generiert → immer aktuell
-- **Drift-Detection:** Inkonsistenzen werden automatisch erkannt und gemeldet
-- **Strukturiert:** Mehrdimensionaler Navigationsraum mit 5 Dimensionen
-- **Semantisch:** Rollenbasierte Doku-Tiefe (Public-APIs tiefer dokumentiert)
-- **ADR-verknüpft:** Architektur-Entscheidungen direkt im Code-Kontext
-
-**Quantifizierbare Verbesserungen:**
-- **Zeitersparnis:** Keine manuelle Dokumentationspflege mehr erforderlich
-- **Aktualität:** Dokumentation ist immer synchron mit Code (Drift-Detection)
-- **Qualität:** Public-APIs vollständig dokumentiert, Infra nicht überladen
-
-### 6.2 Wissensaufbereitung
-
-#### Vorher
-
-- **Dokumentation isoliert:** Dokumentation ist getrennt von Code, schwer zu finden
-- **ADRs isoliert:** Architektur-Entscheidungen sind isoliert von betroffenen Modulen
-- **Keine Zeit-Dimension:** Änderungen sind schwer nachvollziehbar, keine Änderungsmuster erkennbar
-- **Keine Beziehungen:** Abhängigkeiten sind nicht visualisiert
-
-#### Nachher
-
-- **Mehrdimensionaler Raum:** Koordinaten-System ermöglicht gezielte Navigation
-- **ADR-Verknüpfung:** Wissens-Raum als Landkarte, Architektur-Entscheidungen direkt verknüpft
-- **Change Report:** Zeit-Dimension für Änderungsmuster und Trends
-- **Symbol-Index:** Schnelle Suche und Impact-Analyse
-- **Dependency-Graph:** Beziehungen visualisiert (127 Knoten)
-
-**Quantifizierbare Verbesserungen:**
-- **Navigation:** 5 Dimensionen für gezielte Suche
-- **ADR-Zugriff:** 24 ADRs automatisch verknüpft mit Modulen
-- **Impact-Analyse:** Abhängigkeiten in Sekunden analysierbar
-
-### 6.3 Softwareentwicklung
-
-#### Vorher
-
-- **Manuelle Dokumentation:** Zeitaufwand für Dokumentationspflege, Dokumentation veraltet schnell
-- **Keine Validierung:** Fehler werden nicht erkannt, Inkonsistenzen bleiben unbemerkt
-- **Keine Impact-Analyse:** Änderungen sind schwer abschätzbar, Abhängigkeiten unbekannt
-- **Keine AI-Integration:** Keine strukturierte Agent-Kommunikation
-
-#### Nachher
-
-- **Reality-Driven Development:** Code als einzige Wahrheitsquelle, Verification-Loops verhindern Halluzinationen
-- **Verification-Loops:** System-enforced Verification vor/nach Implementierung
-- **Impact-Analyse:** Abhängigkeiten werden verstanden, Änderungen abschätzbar
-- **CI/CD-Integration:** Automatische Validierung bei jedem Push/PR
-- **AI-Agent-Integration:** Strukturierte Workflows via MCP-Server und Cursor Rules
-- **Semantische Klassifizierung:** Public-APIs vs. Infra unterscheiden, Fokus auf wichtige APIs
-
-**Quantifizierbare Verbesserungen:**
-- **Zeitersparnis:** Keine manuelle Dokumentationspflege, automatische Validierung
-- **Qualität:** Public-APIs vollständig dokumentiert und validiert
-- **Fehlerreduktion:** Drift-Detection erkennt Inkonsistenzen automatisch
-- **AI-Effizienz:** Strukturierte Agent-Kommunikation via MCP-Server (99 Resources)
-
----
-
-## Zusammenfassung
-
-Noyrax ist ein **AI-natives Dokumentationssystem** mit folgenden Alleinstellungsmerkmalen:
-
-1. **Automatische Generierung** mit Drift-Detection
-2. **Semantische Intelligenz** (SymbolClassifier, rollenbasierte Doku-Tiefe)
-3. **Mehrdimensionaler Navigationsraum** (5 Dimensionen)
-4. **ADR-Integration** (automatische Verknüpfung)
-5. **MCP-Server** (99 Resources für strukturierten Agent-Zugriff)
-6. **Reality-Driven Development** (Verification-Loops verhindern Halluzinationen)
-
-Diese Features machen Noyrax zu einem **einzigartigen System** für moderne Softwareentwicklung mit AI-Agenten.
-
----
-
-**Referenzen:**
-- ADR-020: API-Doku-Tiefe & SignatureFormatter
-- ADR-021: Semantische API-Dokus & SymbolClassifier
--+-+-+-+-+-+-+-+-+-+-+-+
-- ADR-022: Semantisches Klassen- und Konstanten-Rendering
-- ADR-023: ADR-Verknüpfung mit Modul-Dokumentation
-- ADR-024: Cursor Rules Überarbeitung – Mehrdimensionaler Navigationsraum
-- ADR-025: MCP-Server Tools Scan/Validate – CLI-Bridge-Pattern
-- ADR-026: Reality-Driven Development System
-- ADR-027: Scanner-Excludes und Union-Logik-Fix
-- ADR-028: Vollständige src-Abdeckung & Resync-Strategie
-- ADR-029: Parser-Flow-Kopplung und Sync/Drift-Modi für die Validierung
-