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

package/docs/adr/029-parser-flow-kopplung-und-sync-drift-modi.md

@@ -1,102 +0,0 @@
-# ADR-029: Parser-Flow-Kopplung und Sync/Drift-Modi für die Validierung
-
-## Status
-
-- Status: Accepted  
-- Datum: 2025-12-15
-
-## Kontext
-
-Das System besitzt zwei Haupt-Flows, die Symbole aus dem Code extrahieren:
-
-1. **Generate-Flow (Extension / Full Cycle)**  
-   - `generateDocumentationTs` in `src/extension.ts`  
-   - Pfad: `scanWorkspace` → Parser (`TsJsParser`, `JsonYamlParser`, `PythonParser`) →  
-     `allSymbols`/`allDependencies` → `symbolsUnion`/`dependenciesUnion` →  
-     `generatePerFileDocs` (`docs/modules/*`), `buildIndexFromSymbols` (`docs/index/symbols.jsonl`),  
-     `generateMermaidGraph`/`generateDependencyOverview` (`docs/system/DEPENDENCY_GRAPH.md` / `DEPENDENCIES.md`),  
-     `generateChangeReport` (`docs/system/CHANGE_REPORT.md`) und Caches unter `docs/.cache`.
-
-2. **Validate-Flow (CLI & Extension)**  
-   - CLI: `runValidateCli` in `src/cli/validate-cli.ts` (`npm run validate:cli`)  
-   - Extension: `validateDocumentationTs` in `src/extension.ts` (Command `noyrax.validate`)  
-   - Bisheriger Pfad: erneuter `scanWorkspace` → eigene Parser-Instanzen → `allSymbols` →  
-     `computeCoverage`, `validateMarkdownDir`, `validateSignatureMatching`.
-
-Diese Trennung führte dazu, dass Generator und Validator in bestimmten Fällen unterschiedliche Symbolzustände sahen, was zu `stale_docs`-Warnungen führte, obwohl die Doku frisch generiert war.
-
-## Problem
-
-- Nach einem Full Cycle lag ein aktueller Symbol-Index (`docs/index/symbols.jsonl`) und frische Modul-Doku vor.  
-- Der Validator (`validate:cli` / `validateDocumentationTs`) hat jedoch **erneut geparst** und auf Basis dieses zweiten Parser-Laufs `expected`-Signaturen erzeugt.  
-- In einigen Fällen (insbesondere Skripte unter `scripts/verify-*.js` und Extension-Funktionen in `src/extension.ts`) waren diese Signaturen tiefer typisiert als die Symbole aus dem Generate-Flow, wodurch das Signatur-Matching `stale_docs` meldete, obwohl kein echter Drift zwischen „gerade generierter Doku“ und Symbolbasis bestand.
-- Gleichzeitig soll der Validator weiterhin in der Lage sein, **echten Drift** zu erkennen, wenn sich der Code **nach** einem Generate-Lauf ändert, ohne dass sofort neu generiert wird.
-
-## Entscheidung
-
-Wir führen zwei explizite Validierungsmodi und eine gemeinsame Symbolbasis ein:
-
-1. **Gemeinsame Symbolbasis über `docs/index/symbols.jsonl`**
-
-   - In `src/index/index.ts` wurde `readSymbolsFromIndex(indexFile: string): ParsedSymbol[]` eingeführt.  
-   - Diese Funktion liest `docs/index/symbols.jsonl` (JSONL) und rekonstruiert daraus `ParsedSymbol[]` mit allen für Validator und Generator relevanten Feldern (`filePath`, `fullyQualifiedName`, `kind`, `signature`).
-   - Der Generate-Flow nutzt weiterhin `buildIndexFromSymbols` + `writeJsonlIndex`, der Validator kann nun dieselbe Index-Datei als *kanonische Symbolbasis* verwenden.
-
-2. **Sync-Modus (nach Generate oder Full Cycle)**
-
-   - **CLI-Validator (`src/cli/validate-cli.ts`)**:
-     - Versucht zuerst, Symbole aus `docs/index/symbols.jsonl` zu laden:
-       - `const indexFile = path.join(workspaceRoot, outputPath, 'index', 'symbols.jsonl');`
-       - `allSymbols = readSymbolsFromIndex(indexFile);`
-     - Wenn das Laden gelingt (`allSymbols.length > 0`), arbeitet der Validator im **Sync-Modus**:
-       - Keine erneute Parser-Ausführung, keine zweite Symbolquelle.
-       - Coverage (`computeCoverage`) und Markdown/Signatur-Matching (`validateMarkdownDir` + `validateSignatureMatching`) laufen auf exakt derselben Symbolbasis, die auch für die letzte Generierung verwendet wurde.
-   - **Extension-Validator (`validateDocumentationTs` in `src/extension.ts`)**:
-     - Nutzt den gleichen Mechanismus: erst Index lesen, dann nur bei Bedarf Re-Parse (siehe Drift-Modus).
-   - Ergebnis: Direkt nach `Generate` oder `Full Cycle` gibt es keine künstlichen `stale_docs`-Warnungen mehr – Generator und Validator sehen denselben Symbolzustand.
-
-3. **Drift-Modus (späterer Check ohne frisches Generate)**
-
-   - Wenn `readSymbolsFromIndex` keine Symbole liefert (Index fehlt, leer oder explizit deaktiviert), fällt der Validator in den **Drift-Modus** zurück:
-     - Bisheriges Verhalten: `scanWorkspace` → Parser (`TsJsParser`, `JsonYamlParser`, `PythonParser`) → `allSymbols`.
-   - In diesem Modus:
-     - werden Symbole direkt aus dem aktuellen Code neu ermittelt,
-     - werden diese gegen bestehende Doku/Signaturspeicher verglichen (z. B. über `validateMarkdownDir` + `validateSignatureMatching` und Signatur-Cache in `src/drift/index.ts`),
-     - kann echter Drift (Code geändert, Doku noch alt) erkannt und gemeldet werden.
-
-4. **Drift-Erkennung im Generate-Flow bleibt bestehen**
-
-   - Im Generate-Flow wird weiterhin `detectDrift` (`src/drift/index.ts`) zwischen altem und neuem Signatur-Cache aufgerufen.  
-   - Diese Drift-Erkennung arbeitet unabhängig vom CLI-Validator und ergänzt den Drift-Modus dort.
-
-## Konsequenzen
-
-### Positiv
-
-- **Kohärente Signaturen im Sync-Modus**: Nach einem Generate/Full Cycle gibt es keine `stale_docs`-Warnungen mehr allein aufgrund unterschiedlicher Parser-Flows – Generator und Validator benutzen dieselbe Symbolbasis (`symbolsUnion` projiziert auf `symbols.jsonl`).
-- **Erhaltene Drift-Erkennung**:  
-  - Der Drift-Modus im Validator (Re-Parse) und die Signatur-Cache-Drift-Erkennung im Generate-Flow bleiben erhalten.  
-  - Echte Abweichungen zwischen Code und Doku werden weiterhin erkannt, wenn sich der Code nach der Generierung verändert.
-- **Performance**:  
-  - Typische „Generate → Validate“-Workflows sparen den zweiten Parser-Durchlauf ein, da der Validator direkt aus dem Index liest.
-  - In CI-Szenarien können `scan:cli`/`generate` vor `validate:cli` laufen, danach läuft die Validierung überwiegend auf Artefakten.
-
-### Negativ / Trade-offs
-
-- Die Logik im Validator wird komplexer:
-  - Zwei Modi (Sync vs Drift), abhängig davon, ob ein aktueller Index vorhanden ist.
-  - Fehlerbilder müssen im Debugging klar voneinander unterschieden werden (künstliche vs. echte `stale_docs`).
-- `readSymbolsFromIndex` rekonstruiert die Sprache (`language`) derzeit als `'unknown'`, weil der Index dieses Feld nicht speichert.  
-  - Für aktuelle Uses (Coverage, Signatur-Matching) ist das ausreichend, könnte aber in der Zukunft erweitert werden.
-
-## Auswirkungen auf zukünftige Arbeit
-
-- Bei Änderungen an der Struktur von `IndexRow` oder an `symbolsUnion` muss `readSymbolsFromIndex` mitangepasst werden, damit Generator und Validator weiterhin dieselbe Symbolbasis sehen.
-- Zusätzliche Tests sind sinnvoll:
-  - Sync-Modus: Nach Full Cycle → `validate:cli` sollte keine unerwarteten `stale_docs` melden.  
-  - Drift-Modus: Nach Codeänderungen ohne neues Generate → `validate:cli` sollte Drift korrekt erkennen.
-- Weitere Verbesserungen sind möglich, z. B.:
-  - Ergänzung eines Flags/Arguments, um den Drift-Modus im CLI explizit zu erzwingen (z. B. `--force-reparse`),
-  - Erweiterung des Validierungs-Outputs um eine explizite Kennzeichnung, ob der Lauf im Sync- oder Drift-Modus stattfand.
-
-

package/docs/adr/030-dependency-import-symbol-names-preservation.md

@@ -1,123 +0,0 @@
-# ADR-030: Dependency Import Symbol Names Preservation (Index JSONL)
-
-**Status:** ACCEPTED
-
-**Date:** 2025-12-16
-
-## Context
-
-Der Documentation-System-Index (`docs/index/symbols.jsonl`) enthielt bisher nur modul-basierte Dependency-Informationen (`dependencies?: string[]` mit Import-Pfaden).
-Der Parser extrahiert jedoch bereits importierte Symbolnamen (`ModuleDependency.symbols?: string[]`), diese Information ging beim Bau des JSONL-Index in
-`buildIndexFromSymbols` verloren.
-
-Dadurch wurden nachgelagerte Systeme (Database Plugin, Semantic Brain Plugin) gezwungen, nur mit Modul-Pfaden zu arbeiten und mussten fehlende
-Target-Symbole heuristisch erraten. Das führte zu ungenauen oder aufgeblähten Dependency-Graphen und machte präzise Kanten (Symbol → importiertes Symbol)
-unmöglich.
-
-Gleichzeitig ist der JSONL-Index bereits im Einsatz und muss rückwärtskompatibel bleiben – bestehende Pipelines dürfen durch die Umstellung nicht brechen.
-
-## Decision
-
-Wir erweitern das Index-Format so, dass importierte Symbolnamen pro Zielmodul erhalten bleiben, ohne das bestehende JSONL-Schema zu brechen:
-
-- Einführung eines neuen `DependencyEntry`-Typs für Dependencies im Index:
-  - `module: string` – Zielmodul / Import-Pfad
-  - `symbols?: string[]` – importierte/exportierte Symbolnamen (optional für Backward Compatibility)
-- Erweiterung von `IndexRow.dependencies` auf einen Union-Typ:
-  - `dependencies?: string[] | DependencyEntry[]`
-  - `string[]`: Legacy-Format (nur Modulpfade, unverändert)
-  - `DependencyEntry[]`: neues Format mit Symbolnamen pro Modul
-- Anpassung von `buildIndexFromSymbols`, um:
-  - Dependencies pro Datei (`from`) und Zielmodul (`to`) zu gruppieren,
-  - Symbolnamen je Modul zu mergen, zu deduplizieren und alphabetisch zu sortieren,
-  - ein deterministisches `DependencyEntry[]` je Datei zu erzeugen.
-
-Neue Index-Dateien verwenden immer das strukturierte `DependencyEntry[]`-Format, bestehende Konsumenten, die nur `string[]` kennen, bleiben funktionsfähig,
-da `readSymbolsFromIndex` `dependencies` nicht auswertet.
-
-## Implementation Claims
-
-### Files Created/Modified
-- [x] `src/index/index.ts` – Erweiterung von `IndexRow` und Anpassung von `buildIndexFromSymbols` auf `DependencyEntry[]`.
-
-### Functions/Classes Implemented
-- [x] `DependencyEntry` Interface in `src/index/index.ts` – strukturiert modul- und symbolbasierte Dependencies.
-- [x] `buildIndexFromSymbols()` in `src/index/index.ts` – gruppiert `ModuleDependency` je Datei/Modul, mergen und sortiert Symbolnamen deterministisch.
-
-### Verification Commands
-
-```powershell
-# Datei- und Typ-Verifikation (PowerShell)
-Test-Path documentation-system-plugin/src/index/index.ts
-Get-Content documentation-system-plugin/src/index/index.ts | Select-String "export interface DependencyEntry"
-Get-Content documentation-system-plugin/src/index/index.ts | Select-String "dependencies\?: string\[] \| DependencyEntry\[]"
-
-# Build-Funktion prüfen
-Get-Content documentation-system-plugin/src/index/index.ts | Select-String "buildIndexFromSymbols"
-
-# Architektur- und Import-Verification für das Plugin
-cd documentation-system-plugin
-npm run verify:all
-```
-
-```bash
-# Bash-Äquivalente
-ls documentation-system-plugin/src/index/index.ts
-grep "export interface DependencyEntry" documentation-system-plugin/src/index/index.ts
-grep "dependencies\?: string\[] \| DependencyEntry\[]" documentation-system-plugin/src/index/index.ts
-
-cd documentation-system-plugin
-npm run verify:all
-```
-
-## Verification Report
-
-**Verification Date:** 2025-12-16
-
-**Results:**
-- [x] All files created: YES
-- [x] All functions implemented: YES
-- [x] Compiles without errors: YES (implizit über `npm run verify:all`)
-- [x] Tests pass: YES (bestehende Test-Suite, keine neuen Tests erforderlich für diesen Schritt)
-- [x] Verification scripts pass: YES (`npm run verify:all`)
-
-**Evidence:**
-
-```text
-> npm run verify:all
-
-🚀 Starting architecture verification...
-✅ Architecture verification PASSED
-🚀 Starting ADR claims verification...
-📊 Verification Summary:
-   Total claims: 19
-   Verified: 19
-   Errors: 0
-   Warnings: 0
-✅ ADR verification PASSED
-🚀 Starting import verification...
-📁 Found 39 TypeScript files
-✅ Checked 39 files
-📊 Verification Summary:
-   Errors: 0
-   Warnings: 0
-✅ Import verification PASSED
-```
-
-## Consequences
-
-- Positiv:
-  - Importierte Symbolnamen bleiben durchgehend bis in nachgelagerte Systeme erhalten.
-  - Der Index bleibt deterministisch (sortierte Module und Symbolnamen, keine doppelten Einträge).
-  - Bestehende JSONL-Dateien bleiben gültig; neue Scans erzeugen das reichhaltigere Format.
-- Neutral:
-  - Konsumenten, die `dependencies` bisher ignorieren (z.B. `readSymbolsFromIndex`), bleiben unverändert.
-- Negativ:
-  - Downstream-Reader, die explizit `string[]` für `dependencies` erwarten, müssen zukünftig das Union-Format berücksichtigen.
-
-## Notes
-
-- Diese ADR bildet die Grundlage für weiterführende ADRs im Database Plugin und im Semantic Brain Plugin, die das neue
-  Dependency-Format in die Datenbank und in symbol-basierte Graph-Kanten überführen.
-
-

package/docs/adr/031-generate-cli-vollstaendige-dokumentation.md

@@ -1,99 +0,0 @@
-# ADR-031: Generate-CLI für vollständige Dokumentationsgenerierung
-
-## Status
-Accepted
-
-## Kontext
-
-Die bestehenden CLI-Tools (`scan-cli.ts`, `validate-cli.ts`) wurden für spezifische Aufgaben entwickelt:
-- `scan-cli.ts`: Scannt Symbole und gibt JSON aus
-- `validate-cli.ts`: Validiert Dokumentation gegen Code
-
-Jedoch generieren diese Tools **keine Dokumentations-Artefakte**:
-- `docs/modules/*.md` (Modul-Dokumentation)
-- `docs/index/symbols.jsonl` (Symbol-Index mit DependencyEntry[])
-- `docs/system/DEPENDENCIES.md` (Import-Übersicht)
-- `docs/system/DEPENDENCY_GRAPH.md` (Mermaid-Graph)
-- `docs/system/CHANGE_REPORT.md` (Änderungsprotokoll)
-
-Diese Artefakte wurden bisher nur von der VS Code Extension (`extension.ts`) generiert, was bedeutete:
-1. `npm run compile` in anderen Plugins generierte keine vollständige Dokumentation
-2. Die `symbols.jsonl` enthielt das Legacy-Format statt des neuen `DependencyEntry[]` Formats
-3. Das Database Plugin konnte keine präzisen Target-Symbole aus der Dokumentation extrahieren
-
-## Entscheidung
-
-Erstellung einer neuen `generate-cli.ts`, die die vollständige Dokumentationsgenerierung ohne VS Code APIs ermöglicht.
-
-### Architektur
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                    generate-cli.ts                          │
-├─────────────────────────────────────────────────────────────┤
-│  1. Workspace scannen (scanWorkspace)                       │
-│  2. Parser initialisieren (TsJs, Python, JsonYaml)          │
-│  3. Symbole extrahieren (ParsedSymbol[])                    │
-│  4. Dependencies extrahieren (ModuleDependency[])           │
-│  5. Union-Logik anwenden (bestehende + neue Symbole)        │
-│  6. Artefakte generieren:                                   │
-│     - docs/modules/*.md                                     │
-│     - docs/index/symbols.jsonl (DependencyEntry[] Format)   │
-│     - docs/system/DEPENDENCIES.md                           │
-│     - docs/system/DEPENDENCY_GRAPH.md                       │
-│     - docs/system/CHANGE_REPORT.md                          │
-└─────────────────────────────────────────────────────────────┘
-```
-
-### Integration in postcompile Workflow
-
-```json
-// semantic-brain-plugin/package.json
-"postcompile": "node ../documentation-system-plugin/out/cli/generate-cli.js && node ../documentation-system-plugin/out/cli/validate-cli.js && node ../database-plugin/out/cli/ingest-cli.js"
-
-// database-plugin/package.json
-"postcompile": "node ../documentation-system-plugin/out/cli/generate-cli.js && node ../documentation-system-plugin/out/cli/validate-cli.js && node out/cli/ingest-cli.js"
-```
-
-### Workflow
-
-```
-npm run compile
-    │
-    ▼
-tsc -p ./
-    │
-    ▼
-postcompile Hook
-    │
-    ├──▶ generate-cli.js  ──▶ Generiert docs/ Artefakte
-    │
-    ├──▶ validate-cli.js  ──▶ Validiert Dokumentation
-    │
-    └──▶ ingest-cli.js    ──▶ Importiert in Datenbank
-```
-
-## Konsequenzen
-
-### Positiv
-- `npm run compile` generiert jetzt vollständige Dokumentation
-- `symbols.jsonl` enthält das neue `DependencyEntry[]` Format mit Symbol-Namen
-- Database Plugin kann präzise Target-Symbole extrahieren
-- Semantic Brain Plugin erhält korrekte Dependency-Informationen
-- Konsistenter Workflow über alle Plugins hinweg
-
-### Negativ
-- Zusätzliche CLI-Datei zu warten
-- Duplizierung von Logik aus `extension.ts` (bewusste Entscheidung für CLI-Unabhängigkeit)
-
-## Betroffene Dateien
-
-- `src/cli/generate-cli.ts` (NEU)
-- `package.json` (neues Script `generate:cli`)
-
-## Verwandte ADRs
-
-- ADR-025: MCP Tools Scan Validate CLI Bridge
-- ADR-029: Parser Flow Kopplung und Sync Drift Modi
-- ADR-030: Dependency Import Symbol Names Preservation
-

package/docs/adr/032-windows-optimized-verification-scripts.md

@@ -1,165 +0,0 @@
-# ADR-032: Windows-optimierte Verification-Scripts und MCP-Server Integration
-
-**Status:** Accepted  
-**Datum:** 2025-12-18  
-**Autor:** AI-Agent  
-**Bezug:** ADR-026 (Reality-Driven Development System), Root ADR-002
-
-## Kontext
-
-Die bestehenden Verification-Scripts (`scripts/verify-adrs.js`) verwendeten Shell-Befehle wie `grep` für die Suche nach Funktionen/Klassen im Code. Auf Windows führte dies zu Fehlermeldungen:
-
-```
-Das System kann den angegebenen Pfad nicht finden.
-```
-
-Obwohl die Verification erfolgreich war (Exit Code 0), waren die Fehlermeldungen verwirrend und unprofessionell.
-
-## Entscheidung
-
-Wir optimieren die Verification-Scripts für Windows:
-
-### 1. Native Node.js-Funktionen statt Shell-Befehle
-
-**Vorher (Shell-basiert):**
-```javascript
-const result = execSync(
-  `grep -r "\\b${claim.name}\\b" src/ 2>/dev/null || echo ""`,
-  { encoding: 'utf-8', cwd: workspaceRoot }
-);
-```
-
-**Nachher (Node.js-basiert):**
-```javascript
-function searchInDirectory(dir, pattern) {
-  const regex = new RegExp(`\\b${pattern}\\b`);
-  const files = fs.readdirSync(dir);
-  
-  for (const file of files) {
-    const filePath = path.join(dir, file);
-    const stat = fs.statSync(filePath);
-    
-    if (stat.isDirectory()) {
-      if (searchInDirectory(filePath, pattern)) {
-        return true;
-      }
-    } else if (file.endsWith('.ts') || file.endsWith('.js')) {
-      const content = fs.readFileSync(filePath, 'utf-8');
-      if (regex.test(content)) {
-        return true;
-      }
-    }
-  }
-  return false;
-}
-```
-
-### 2. Vorteile der neuen Implementierung
-
-- **Plattformunabhängig:** Funktioniert auf Windows, Linux, macOS
-- **Keine externen Abhängigkeiten:** Nur Node.js-Standardbibliotheken
-- **Saubere Ausgabe:** Keine Shell-Fehlermeldungen
-- **Konsistent:** Gleiche Implementierung in allen Plugins
-
-## Implementation Claims
-
-### Aktualisierte Dateien
-
-- `scripts/verify-adrs.js`
-
-## Verification Commands
-
-```powershell
-# Vorher (mit Fehlermeldungen)
-npm run verify:adrs
-# Output: "Das System kann den angegebenen Pfad nicht finden." (mehrfach)
-# ✅ ADR verification PASSED
-
-# Nachher (sauber)
-npm run verify:adrs
-# Output: Keine Fehlermeldungen
-# ✅ ADR verification PASSED
-```
-
-## Testergebnisse
-
-```
-🚀 Starting ADR claims verification...
-
-📊 Verification Summary:
-   Total claims: 19
-   Verified: 19
-   Errors: 0
-   Warnings: 0
-
-✅ ADR verification PASSED
-```
-
-## Konsequenzen
-
-### Positiv
-
-1. **Saubere Ausgabe:** Keine verwirrenden Fehlermeldungen
-2. **Plattformunabhängig:** Funktioniert auf allen Betriebssystemen
-3. **Wartbar:** Einfacher zu debuggen und erweitern
-4. **Konsistent:** Alle Plugins verwenden die gleiche Implementierung
-
-### Zu beachten
-
-1. **Performance:** Native Node.js ist möglicherweise langsamer als `grep` für sehr große Codebases
-2. **Speicher:** Dateien werden komplett in den Speicher geladen
-
-## MCP-Server Integration
-
-Zusätzlich zur Windows-Optimierung wurde ein neues Tool zum MCP-Server hinzugefügt:
-
-### Neues Tool: `validation/verifyAdrs`
-
-```typescript
-// MCP-Tool-Definition
-{
-  name: 'validation/verifyAdrs',
-  description: 'Verifiziert ADR-Claims gegen den Code. Prüft Datei-Existenz und Funktions-Existenz.',
-  inputSchema: {
-    type: 'object',
-    properties: {
-      verbose: {
-        type: 'boolean',
-        description: 'Optional: Ausführliche Ausgabe mit Warnungen. Default: false',
-      },
-    },
-  },
-}
-```
-
-### Erstellte Dateien
-
-- `mcp/src/tools/verify-adrs.ts`
-- `packages/doc-system-agent/src/mcp/tools/verify-adrs.ts`
-
-### Aktualisierte Dateien
-
-- `mcp/src/server.ts` (Tool registriert)
-- `packages/doc-system-agent/src/mcp/server.ts` (Tool registriert)
-- `packages/doc-system-agent/src/mcp/types.ts` (VerifyAdrsRequest/Response Typen)
-- `packages/doc-system-agent/templates/cursor-rules/026-reality-driven-verification.mdc` (Dokumentation)
-
-### Nutzung via MCP
-
-Agenten können jetzt ADR-Verification über das MCP-Protokoll aufrufen:
-
-```json
-{
-  "method": "tools/call",
-  "params": {
-    "name": "validation/verifyAdrs",
-    "arguments": { "verbose": true }
-  }
-}
-```
-
-## Referenzen
-
-- ADR-026: Reality-Driven Development System
-- Root ADR-002: Systemweite ADR-Verification Integration
-

package/docs/adr/036-enhanced-dependency-metadata.md

@@ -1,190 +0,0 @@
-# ADR-036: Enhanced Dependency Metadata (Aliasing, Type-Only, Re-Exports)
-
-## Status
-Accepted
-
-## Kontext
-
-Nach der erfolgreichen Implementierung der präzisen Symbol-Dependencies (ADR-030, ADR-033, ADR-034, ADR-035) wurden drei zusätzliche Edge-Cases identifiziert, die für eine robuste semantische Analyse wichtig sind:
-
-1. **Aliasing / Default Imports / Namespace Imports**
-2. **Type-only Imports**
-3. **Re-Exports / Barrel-Pattern**
-
-## Entscheidung
-
-### 1. Aliasing-Unterstützung
-
-Import-Aliase werden jetzt vollständig erfasst:
-
-| Import-Typ | Beispiel | Gespeichert als |
-|------------|----------|-----------------|
-| Named Import | `import { X } from ...` | `"X"` |
-| Alias Import | `import { X as Y } from ...` | `"X as Y"` |
-| Default Import | `import X from ...` | `"default as X"` |
-| Namespace Import | `import * as M from ...` | `"* as M"` |
-
-**Implementierung** (`dependencies.ts`):
-```typescript
-const namedImports = imp.getNamedImports().map(ni => {
-    const name = ni.getName();
-    const alias = ni.getAliasNode()?.getText();
-    let result = name;
-    if (alias && alias !== name) {
-        result = `${name} as ${alias}`;
-    }
-    return result;
-});
-```
-
-### 2. Type-Only Imports
-
-Type-only Imports werden mit `type` Prefix markiert:
-
-| Import-Typ | Beispiel | Gespeichert als |
-|------------|----------|-----------------|
-| Type Import | `import type { X } from ...` | `"type X"` |
-| Type Alias | `import type { X as Y } from ...` | `"type X as Y"` |
-| Type Namespace | `import type * as M from ...` | `"type * as M"` |
-| Mixed | `import { type X, Y } from ...` | `["type X", "Y"]` |
-
-**Zusätzlich**: `isTypeOnly: true` Flag auf Dependency-Ebene wenn **alle** Imports type-only sind.
-
-**Auswirkung auf Scoring**:
-- Type-only Imports haben geringeren Coupling-Impact
-- Empfohlener Weight-Faktor: `0.3` statt `1.0`
-- Können bei Dead-Code-Detection ignoriert werden (werden zur Laufzeit entfernt)
-
-### 3. Re-Exports / Barrel-Pattern
-
-Re-Exports werden mit `isReexport: true` markiert:
-
-```typescript
-// Barrel-File: src/api/index.ts
-export { GraphApi } from './graph-api';
-export * from './models';
-```
-
-Gespeichert als:
-```json
-{
-  "module": "./graph-api",
-  "symbols": ["GraphApi"],
-  "isReexport": true
-}
-```
-
-**Semantische Bedeutung**:
-- Re-Exports sind **Durchleitungen**, keine echten Dependencies
-- Für Coupling-Analyse: Das Barrel-File ist nicht der echte Konsument
-- Für Import-Path-Analyse: Kann zur Vereinfachung von Import-Pfaden genutzt werden
-
-## Datenformat
-
-### ModuleDependency (Parser-Output)
-
-```typescript
-interface ModuleDependency {
-    from: string;     // Quell-Datei
-    to: string;       // Ziel-Modul
-    type: 'import' | 'export' | 'require';
-    symbols?: string[];    // Format: "Name", "Name as Alias", "type Name", "* as Namespace"
-    isTypeOnly?: boolean;  // true wenn alle Imports type-only
-    isReexport?: boolean;  // true wenn Re-Export (Barrel-Pattern)
-}
-```
-
-### DependencyEntry (symbols.jsonl)
-
-```typescript
-interface DependencyEntry {
-    module: string;
-    symbols?: string[];    // Dedupliziert und sortiert
-    isTypeOnly?: boolean;  // true wenn alle Imports type-only
-    isReexport?: boolean;  // true wenn mindestens ein Re-Export
-}
-```
-
-## Beispiel-Output
-
-```json
-{
-  "symbol_id": "ts://src/extension.ts#activate(...)",
-  "dependencies": [
-    {
-      "module": "./config",
-      "symbols": ["type Config", "type Options"],
-      "isTypeOnly": true
-    },
-    {
-      "module": "./utils",
-      "symbols": ["X as Y", "Z"]
-    },
-    {
-      "module": "vscode",
-      "symbols": ["* as vscode"]
-    }
-  ]
-}
-```
-
-## Konsequenzen
-
-### Positiv
-- **Präzise Alias-Auflösung**: Welcher lokale Name wird verwendet?
-- **Type-only Unterscheidung**: Ermöglicht differenzierte Coupling-Analyse
-- **Barrel-Detection**: Identifiziert Re-Export-Ketten für bessere Graph-Analyse
-- **Zukunftssicher**: Grundlage für Import-Optimierung und Dead-Code-Detection
-
-### Negativ
-- **Größere symbols.jsonl**: Zusätzliche Metadaten pro Dependency
-- **Komplexere Parsing-Logik**: Mehr Edge-Cases zu behandeln
-- **Downstream-Anpassungen**: Database-Plugin und Semantic-Brain müssen aktualisiert werden
-
-## Empfohlene Scoring-Anpassungen
-
-### CouplingScorer
-
-```typescript
-function calculateWeight(dep: DependencyEntry): number {
-    let weight = dep.symbols?.length ?? 1;
-    
-    // Type-only Imports haben reduzierten Impact
-    if (dep.isTypeOnly) {
-        weight *= 0.3;
-    }
-    
-    // Re-Exports sind Durchleitungen
-    if (dep.isReexport) {
-        weight *= 0.5;
-    }
-    
-    return weight;
-}
-```
-
-### ImportanceScorer
-
-```typescript
-// Type-only Imports nicht für Importance zählen
-const valueImports = deps.filter(d => !d.isTypeOnly);
-const typeImports = deps.filter(d => d.isTypeOnly);
-
-const importance = valueImports.length * 1.0 + typeImports.length * 0.2;
-```
-
-## Betroffene Dateien
-
-- `src/parsers/dependencies.ts` - Dependency-Extraktion mit Aliasing, Type-Only, Re-Export Detection
-- `src/cache/dependencies-cache.ts` - DependencyCacheEntry erweitert um `isTypeOnly` und `isReexport`
-- `src/core/consolidation.ts` - Dependency-Union mit Metadaten-Merge
-- `src/index/index.ts` - DependencyEntry Interface und Aggregation
-- `src/cli/generate-cli.ts` - Full-Modus Cache-Bypass Fix
-
-## Verwandte ADRs
-
-- ADR-030: Dependency Import Symbol Information Loss
-- ADR-033: Edge Metadata Precise Dependencies
-- ADR-034: Postcompile Generate-CLI Integration
-- ADR-035: Präzise Symbol-Dependencies Verifikation
-