From 3be7d617fe89390d0b1a1b866c560654cbdb72e4 Mon Sep 17 00:00:00 2001 From: Lars Date: Mon, 26 Jan 2026 18:53:28 +0100 Subject: [PATCH] Update documentation index to include WP-26 integration details - Added new sections for WP-26 integration, including links to the Lastenheft, interface specification, and implementation checklist. - Enhanced the overall structure of the documentation index to improve navigation and accessibility of WP-26 related resources. --- docs/00_Dokumentations_Index.md | 10 + docs/06_LH_WP26_Plugin_Integration.md | 908 ++++++++++++++++++++ docs/WP26_Implementation_Checklist.md | 358 ++++++++ docs/WP26_Plugin_Interface_Specification.md | 797 +++++++++++++++++ 4 files changed, 2073 insertions(+) create mode 100644 docs/06_LH_WP26_Plugin_Integration.md create mode 100644 docs/WP26_Implementation_Checklist.md create mode 100644 docs/WP26_Plugin_Interface_Specification.md diff --git a/docs/00_Dokumentations_Index.md b/docs/00_Dokumentations_Index.md index 8e7c055..15afe47 100644 --- a/docs/00_Dokumentations_Index.md +++ b/docs/00_Dokumentations_Index.md @@ -21,6 +21,12 @@ 6. **[06_Konfigurationsdateien_Referenz.md](./06_Konfigurationsdateien_Referenz.md)** - Config-Dateien Format & Aufbau 7. **[07_Event_Handler_Commands.md](./07_Event_Handler_Commands.md)** - Event Handler & Commands +### WP-26 Integration (Section Types & Intra-Note-Edges) + +8. **[06_LH_WP26_Plugin_Integration.md](./06_LH_WP26_Plugin_Integration.md)** - Lastenheft für WP-26 Plugin-Integration (vollständige Anforderungen) +9. **[WP26_Plugin_Interface_Specification.md](./WP26_Plugin_Interface_Specification.md)** - Vollständige Schnittstellenspezifikation für Plugin-Entwicklung +10. **[WP26_Implementation_Checklist.md](./WP26_Implementation_Checklist.md)** - Implementierungs-Checkliste mit Tasks und Phasen + ### Chain Inspector Reports - [CHAIN_INSPECTOR_V0_REPORT.md](./CHAIN_INSPECTOR_V0_REPORT.md) - v0.0 Implementierung @@ -171,6 +177,10 @@ → [03_Entwicklerhandbuch.md](./03_Entwicklerhandbuch.md) → [04_Architektur.md](./04_Architektur.md) +### WP-26 Integration +→ [WP26_Plugin_Interface_Specification.md](./WP26_Plugin_Interface_Specification.md) +→ [WP26_Implementation_Checklist.md](./WP26_Implementation_Checklist.md) + --- **Ende des Dokumentations-Index** diff --git a/docs/06_LH_WP26_Plugin_Integration.md b/docs/06_LH_WP26_Plugin_Integration.md new file mode 100644 index 0000000..70a9b7c --- /dev/null +++ b/docs/06_LH_WP26_Plugin_Integration.md @@ -0,0 +1,908 @@ +# LASTENHEFT: WP-26 Integration im Obsidian Plugin + +**Version:** 1.0 +**Datum:** 25. Januar 2026 +**Status:** Entwurf zur Review +**Projekt:** mindnet_obsidian (Obsidian Community Plugin) +**Basis:** Backend WP-26 v1.3 (Section Types & Intra-Note-Edges) + +--- + +## 1. Einleitung + +### 1.1 Zweck des Dokuments + +Dieses Lastenheft definiert die vollständigen Anforderungen für die Integration der WP-26 Features (Section Types & Intra-Note-Edges) in das bestehende mindnet_obsidian Plugin. Es beschreibt alle notwendigen Anpassungen, Erweiterungen und neuen Funktionen, die erforderlich sind, um die Backend-Funktionalität nahtlos in die Plugin-Benutzeroberfläche zu integrieren. + +### 1.2 Geltungsbereich + +- **Plugin:** mindnet_obsidian (`c:\Dev\cursor\mindnet_obsidian`) +- **Backend-Contract:** WP-26 Lastenheft v1.3 (Section Types & Intra-Note-Edges) +- **Kompatibilität:** Alle bestehenden Funktionen müssen weiterhin funktionieren +- **Integration:** Nahtlose Einbindung ohne Breaking Changes + +### 1.3 Grundprinzipien + +1. **Vollständige Abwärtskompatibilität:** Bestehende Notes und Funktionen funktionieren unverändert +2. **Nahtlose Integration:** Neue Features fügen sich natürlich in bestehende Workflows ein +3. **Keine Deaktivierungen:** Keine Funktionen werden eigenmächtig deaktiviert oder signifikant geändert +4. **Konsistente UX:** Neue UI-Elemente folgen bestehenden Design-Patterns +5. **Backend-Konformität:** Alle generierten Markdown-Formate entsprechen der Backend-Spezifikation + +### 1.4 Definitionen + +| Begriff | Definition | +|---------|------------| +| **Section-Type** | Explizit per `[!section]` Callout definierter Typ für einen Abschnitt | +| **Block-ID** | Obsidian Block-Reference Format `^block-id` in Überschriften | +| **Intra-Note-Edge** | Semantische Kante zwischen Chunks derselben Note (`is_internal: true`) | +| **Effective Type** | Für Scoring verwendeter Typ: `section_type` falls vorhanden, sonst `note_type` | +| **Retroaktive Propagation** | Section-Type gilt ab der vorhergehenden Überschrift, auch wenn Callout später steht | + +--- + +## 2. Analyse der bestehenden Plugin-Struktur + +### 2.1 Betroffene Module + +#### 2.1.1 Parser (`src/parser/`) + +**Aktuelle Funktionen:** +- `parseEdgesFromCallouts.ts`: Extrahiert `[!edge]` Callouts und Targets +- `parseRelLinks.ts`: Extrahiert `[[rel:type|target]]` Links +- `parseFrontmatter.ts`: Extrahiert Frontmatter-Metadaten + +**WP-26 Relevanz:** +- Muss `[!section]` Callouts erkennen +- Muss Block-IDs aus Überschriften extrahieren +- Muss Intra-Note-Links (`[[#^block-id]]`) identifizieren + +#### 2.1.2 Mapping (`src/mapping/`) + +**Aktuelle Funktionen:** +- `sectionParser.ts`: Splittet Markdown in Sections (nach Headings) +- `semanticMappingBuilder.ts`: Erstellt Semantic Mapping Blöcke +- `edgeTypeSelector.ts`: Vorschläge für Edge-Types basierend auf Kontext +- `graphSchema.ts`: Lädt und parst `graph_schema.md` +- `schemaHelper.ts`: Hilfsfunktionen für Schema-Lookups + +**WP-26 Relevanz:** +- Section-Parser muss `[!section]` Callouts und Block-IDs erkennen +- Edge-Type-Selector muss Section-Types berücksichtigen +- Schema-Helper muss Section-Type-basierte Vorschläge liefern + +#### 2.1.3 Interview (`src/interview/`) + +**Aktuelle Funktionen:** +- `renderer.ts`: Rendert Interview-Antworten zu Markdown +- `wizardState.ts`: Verwaltet Wizard-State +- `types.ts`: TypeScript-Interfaces für Interview-Konfiguration +- `sectionKeyResolver.ts`: Löst Section-Keys auf + +**WP-26 Relevanz:** +- Renderer muss `[!section]` Callouts generieren können +- Wizard-State muss Section-Types unterstützen +- Section-Key-Resolver muss Block-IDs berücksichtigen + +#### 2.1.4 Chain Workbench (`src/workbench/`) + +**Aktuelle Funktionen:** +- `todoGenerator.ts`: Generiert TODOs basierend auf Chain-Templates +- `chainInspector.ts`: Analysiert Chains und findet Gaps +- `types.ts`: TypeScript-Interfaces für Workbench + +**WP-26 Relevanz:** +- Chain-Matching muss Section-Types berücksichtigen +- Gap-Detection muss Intra-Note-Edges erkennen +- Template-Matching muss effective types verwenden + +#### 2.1.5 UI (`src/ui/`) + +**Aktuelle Funktionen:** +- `EdgeTypeChooserModal.ts`: Modal zur Edge-Type-Auswahl +- `InlineEdgeTypeModal.ts`: Inline-Edge-Type-Suggester +- `LinkPromptModal.ts`: Modal für Link-Erstellung +- `InterviewWizardModal.ts`: Interview-Wizard-UI + +**WP-26 Relevanz:** +- Edge-Type-Chooser muss Section-Type-basierte Vorschläge zeigen +- Link-Prompt muss Block-ID-Generierung unterstützen +- Interview-Wizard muss Section-Type-Auswahl ermöglichen + +#### 2.1.6 Lint (`src/lint/`) + +**Aktuelle Funktionen:** +- `LintEngine.ts`: Haupt-Lint-Engine +- `rules/`: Verschiedene Lint-Regeln + +**WP-26 Relevanz:** +- Neue Lint-Regeln für Section-Types +- Validierung von Block-IDs +- Validierung von Intra-Note-Edges + +#### 2.1.7 Schema (`src/schema/`) + +**Aktuelle Funktionen:** +- `GraphSchemaLoader.ts`: Lädt `graph_schema.md` + +**WP-26 Relevanz:** +- Muss erweitert werden für Section-Type-Lookups +- Muss "prohibited" Edges unterstützen (Phase 3) + +--- + +## 3. Funktionale Anforderungen + +### 3.1 Phase 1: Grundlagen (Kern-Parsing) + +#### FA-PL-01: Section-Type-Callout-Parsing + +**Anforderung:** Das Plugin muss `[!section]` Callouts erkennen und parsen. + +**Betroffene Dateien:** +- `src/parser/parseEdgesFromCallouts.ts` (erweitern) +- `src/mapping/sectionParser.ts` (erweitern) + +**Implementierung:** +1. Neues Regex-Pattern für `[!section]` Callouts: `/^\s*>\s*\[!section\]\s*(\w+)/i` +2. Section-Parser erkennt Callouts innerhalb von Sections +3. Extrahiert Section-Type (muss in `types.yaml` validiert werden) +4. Speichert Section-Type in `NoteSection` Interface + +**Interface-Erweiterung:** +```typescript +export interface NoteSection { + // ... bestehende Felder ... + sectionType: string | null; // NEU: Section-Type aus [!section] Callout + blockId: string | null; // NEU: Block-ID aus Heading (^block-id) +} +``` + +**Validierung:** +- Section-Type muss in `types.yaml` existieren (Warnung bei unbekanntem Typ) +- Case-insensitive Matching für Callout-Header + +**Kompatibilität:** +- Bestehende Notes ohne `[!section]` Callouts funktionieren unverändert +- `sectionType` ist optional (`null` = Fallback auf `note_type`) + +--- + +#### FA-PL-02: Block-ID-Extraktion + +**Anforderung:** Das Plugin muss Block-IDs aus Überschriften extrahieren. + +**Betroffene Dateien:** +- `src/mapping/sectionParser.ts` (erweitern) + +**Implementierung:** +1. Regex-Pattern für Block-IDs in Headings: `/^#{1,6}\s+.+\s+\^([a-zA-Z0-9_-]+)$/` +2. Extrahiert Block-ID aus Heading-Text (z.B. `## Überschrift ^block-id`) +3. Speichert Block-ID in `NoteSection.blockId` + +**Beispiele:** +```markdown +## Situation ^sit → blockId: "sit" +## Reflexion ^ref → blockId: "ref" +## Überschrift ohne ID → blockId: null +``` + +**Kompatibilität:** +- Bestehende Headings ohne Block-IDs funktionieren unverändert +- Block-ID ist optional + +--- + +#### FA-PL-03: Intra-Note-Link-Erkennung + +**Anforderung:** Das Plugin muss Intra-Note-Links (`[[#^block-id]]`) erkennen. + +**Betroffene Dateien:** +- `src/parser/parseEdgesFromCallouts.ts` (erweitern) +- `src/mapping/sectionParser.ts` (erweitern) + +**Implementierung:** +1. Erweitert Wikilink-Parsing um Block-Reference-Format +2. Erkennt `[[#^block-id]]` als Intra-Note-Link +3. Markiert solche Links als `isInternal: true` in ParsedEdge + +**Interface-Erweiterung:** +```typescript +export interface ParsedEdge { + // ... bestehende Felder ... + isInternal: boolean; // NEU: true für [[#^block-id]] Links + blockId: string | null; // NEU: Block-ID aus [[#^block-id]] +} +``` + +**Kompatibilität:** +- Bestehende Inter-Note-Links funktionieren unverändert +- Intra-Note-Links werden zusätzlich erkannt + +--- + +### 3.2 Phase 2: UI-Komponenten + +#### FA-PL-04: Section-Type-Modal + +**Anforderung:** Neues Modal zur Auswahl und Einfügung von Section-Types. + +**Neue Datei:** +- `src/ui/SectionTypeModal.ts` + +**Funktionalität:** +1. Zeigt verfügbare Section-Types aus `types.yaml` +2. Erlaubt Auswahl eines Section-Types +3. Fügt `[!section]` Callout an aktueller Cursor-Position ein +4. Unterstützt Block-ID-Generierung für Heading + +**UI-Flow:** +1. Command: "Mindnet: Add Section Type" +2. Modal öffnet mit Liste verfügbarer Types +3. Benutzer wählt Type +4. Callout wird eingefügt: `> [!section] ` **direkt nach der Heading-Zeile** +5. Optional: Block-ID wird automatisch generiert für vorhergehende Heading + +**Formatierungsregel:** `[!section]` Callout wird immer direkt nach der Heading-Zeile eingefügt (vor dem Section-Content) + +**Kompatibilität:** +- Bestehende Commands bleiben unverändert +- Neues Command ist optional + +--- + +#### FA-PL-05: Edge-Type-Chooser mit Section-Type-Support + +**Anforderung:** Edge-Type-Chooser muss Section-Types berücksichtigen. + +**Betroffene Dateien:** +- `src/ui/EdgeTypeChooserModal.ts` (erweitern) +- `src/mapping/schemaHelper.ts` (erweitern) + +**Implementierung:** +1. Edge-Type-Chooser erhält `sourceSectionType` und `targetSectionType` Parameter +2. Schema-Helper nutzt Section-Types für Vorschläge (falls vorhanden) +3. Fallback auf `note_type` wenn Section-Type nicht vorhanden +4. Zeigt "Recommended (section types)" Sektion wenn Section-Types vorhanden + +**Priorisierung:** +1. Suggested (from chain_roles) - unverändert +2. Recommended (section types) - NEU +3. Recommended (schema) - erweitert um Section-Types +4. All edge types - unverändert + +**Kompatibilität:** +- Bestehende Funktionalität bleibt unverändert +- Section-Types werden zusätzlich berücksichtigt + +--- + +#### FA-PL-06: Link-Prompt mit Block-ID-Generierung + +**Anforderung:** Link-Prompt muss Block-ID-Generierung unterstützen. + +**Betroffene Dateien:** +- `src/ui/LinkPromptModal.ts` (erweitern) + +**Implementierung:** +1. Erkennt, wenn Link zu Section in aktueller Note erstellt wird +2. Fragt Benutzer, ob Block-ID generiert werden soll +3. Generiert eindeutige Block-ID basierend auf Heading-Text +4. Fügt Block-ID zu Heading hinzu: `## Heading ^generated-id` + +**Beispiel:** +- Benutzer erstellt Link: `[[#Situation]]` +- Plugin erkennt: Intra-Note-Link +- Plugin fragt: "Block-ID 'situation' zu Heading hinzufügen?" +- Bei Bestätigung: Heading wird zu `## Situation ^situation` + +**Kompatibilität:** +- Bestehende Link-Erstellung funktioniert unverändert +- Block-ID-Generierung ist optional + +--- + +### 3.3 Phase 3: Feature-Integration + +#### FA-PL-07: Interview-Wizard mit Section-Types, Block-IDs und automatischen Edge-Vorschlägen + +**Anforderung:** Interview-Wizard muss Section-Types, Block-IDs und automatische Edge-Vorschläge zwischen Sections unterstützen. + +**Betroffene Dateien:** +- `src/interview/renderer.ts` (erweitern) +- `src/interview/types.ts` (erweitern) +- `src/ui/InterviewWizardModal.ts` (erweitern) + +**Implementierung:** + +1. **Section-Types:** + - Interview-Config erlaubt `section_type` in Steps + - Renderer generiert `[!section]` Callouts für Steps mit Section-Type + - Wizard-State speichert Section-Type pro Step + +2. **Block-IDs:** + - Interview-Config erlaubt `block_id` (explizit) oder `generate_block_id: true` (automatisch) + - Automatische Generierung: Slugify des Step-Keys oder Heading-Texts + - Wizard-State trackt alle generierten Block-IDs (`generatedBlockIds` Map) + - Renderer fügt Block-ID zu Heading hinzu: `## Heading ^block-id` + +3. **Referenzen zu vorherigen Sections:** + - Interview-Config erlaubt `references` Array in Steps + - Jede Reference enthält `block_id` und optional `edge_type` + - Renderer generiert `[!edge]` Callouts mit Block-References: `[[#^block-id]]` + - Referenzen werden beim Rendern des aktuellen Steps eingefügt + +4. **Automatische Edge-Vorschläge zwischen Sections:** + - Wizard-State trackt Section-Sequenz (`sectionSequence` Array) + - Für jede neue Section: Automatische Edge-Vorschläge zu vorherigen Sections + - Edge-Types werden aus `graph_schema.md` ermittelt (falls verfügbar) + - Fallback: `related_to` wenn kein Schema-Match gefunden wird + - Rückwärts-Edges werden automatisch vorgeschlagen (inverser Edge-Type via `edge_vocabulary.md`) + +**Config-Erweiterung:** +```yaml +profiles: + - key: experience_profile + note_type: experience + steps: + - type: capture_text + key: context + section: "## Kontext" + section_type: experience + generate_block_id: true # Generiert automatisch "context" + + - type: capture_text + key: situation + section: "## Situation" + section_type: experience + block_id: "sit" # Explizite Block-ID + references: + - block_id: "context" + edge_type: "derived_from" # Optional: Vorgeschlagener Edge-Type + + - type: capture_text + key: reflection + section: "## Reflexion" + section_type: insight + generate_block_id: true # Generiert automatisch "reflection" + # Automatischer Edge-Vorschlag wird generiert: insight -> experience (invers zu resulted_in) +``` + +**Renderer-Logik:** + +1. **Block-ID-Generierung:** + - Wenn `block_id` explizit: Verwende diesen Wert + - Wenn `generate_block_id: true`: Generiere aus Step-Key (slugify) + - Wenn beides fehlt: Keine Block-ID + +2. **Section-Type-Generierung:** + - Wenn `section_type` vorhanden: Generiere `> [!section] ` **direkt nach der Heading-Zeile** + - Wenn Block-ID vorhanden: Heading wird zu `## Heading ^block-id` + - **Formatierungsregel:** `[!section]` Callout steht immer unmittelbar nach der Überschrift, vor dem Section-Content + +3. **Referenz-Generierung:** + - Für jede Reference in `references` Array: + - Generiere `> [!edge] ` (oder `related_to` wenn nicht angegeben) + - Generiere `[[#^block-id]]` Link + - **Formatierungsregel:** Edges werden **am Ende der Sektion** eingefügt (nach dem Section-Content, wie bisher) + +4. **Automatische Edge-Vorschläge:** + - Für jede neue Section (ab der zweiten): + - Ermittle `effective_type` der aktuellen Section (Section-Type oder Note-Type) + - Für jede vorherige Section in Sequenz: + - Ermittle `effective_type` der vorherigen Section + - Lookup in `graph_schema.md`: `getTopologyInfo(prevType, currentType)` + - Wenn Match gefunden: Generiere Forward-Edge mit typischem Edge-Type + - Generiere automatisch Rückwärts-Edge mit inversem Edge-Type (via `edge_vocabulary.md`) + - Automatische Edges werden nur generiert, wenn beide Sections Block-IDs haben + - **Formatierungsregel:** Automatische Edges werden **am Ende der Sektion** eingefügt (nach dem Section-Content) + +**Generierte Ausgabe (Beispiel):** +```markdown +## Kontext ^context +> [!section] experience + +[Antwort aus Step "context"] + +> [!edge] derived_from +> [[#^context]] + +## Situation ^sit +> [!section] experience + +[Antwort aus Step "situation"] + +> [!edge] resulted_in +> [[#^sit]] +> [!edge] caused_by +> [[#^context]] + +## Reflexion ^reflection +> [!section] insight + +[Antwort aus Step "reflection"] + +> [!edge] resulted_in +> [[#^sit]] +> [!edge] caused_by +> [[#^context]] +``` + +**Formatierungsregeln:** +1. `> [!section] ` steht **immer direkt nach der Heading-Zeile** (vor dem Section-Content) +2. `> [!edge]` Callouts stehen **immer am Ende der Sektion** (nach dem Section-Content, wie bisher) +3. Leerzeile zwischen Heading und `[!section]` Callout ist optional (kann weggelassen werden) +4. Leerzeile zwischen Section-Content und Edges ist optional (kann weggelassen werden) + +**Wizard-State-Erweiterung:** +```typescript +export interface WizardState { + // ... bestehende Felder ... + generatedBlockIds: Map; + sectionSequence: Array<{ // NEU: Sequenz aller Sections für Edge-Vorschläge + stepKey: string; + blockId: string | null; + sectionType: string | null; + noteType: string; // Fallback für effective_type + }>; +} +``` + +**Kompatibilität:** +- Bestehende Interview-Configs ohne neue Felder funktionieren unverändert +- Alle neuen Felder sind optional +- Block-ID-Generierung ist standardmäßig deaktiviert (muss explizit aktiviert werden) +- Automatische Edge-Vorschläge werden nur generiert, wenn beide Sections Block-IDs haben + +--- + +#### FA-PL-08: Chain Workbench mit Section-Types + +**Anforderung:** Chain Workbench muss Section-Types für Chain-Matching verwenden. + +**Betroffene Dateien:** +- `src/workbench/chainInspector.ts` (erweitern) +- `src/workbench/todoGenerator.ts` (erweitern) +- `src/workbench/types.ts` (erweitern) + +**Implementierung:** +1. Chain Inspector verwendet `effective_type` (Section-Type oder Note-Type) +2. Template-Matching berücksichtigt Section-Types +3. Gap-Detection erkennt fehlende Section-Types +4. TODO-Generator schlägt Section-Types vor + +**Logik:** +- Für jeden Chunk: `effectiveType = sectionType || noteType` +- Template-Matching: `template.slot.type === effectiveType` +- Gap-Detection: Wenn Template `experience` Slot erwartet, aber Section hat `insight` → Gap + +**Kompatibilität:** +- Bestehende Chain-Analysen funktionieren unverändert +- Section-Types werden zusätzlich berücksichtigt + +--- + +#### FA-PL-09: Semantic Mapping mit Section-Types + +**Anforderung:** Semantic Mapping Builder muss Section-Types berücksichtigen. + +**Betroffene Dateien:** +- `src/mapping/semanticMappingBuilder.ts` (erweitern) +- `src/mapping/edgeTypeSelector.ts` (erweitern) + +**Implementierung:** +1. Mapping Builder erkennt Section-Types in Sections +2. Edge-Type-Selector verwendet Section-Types für Vorschläge +3. Automatische Edge-Generierung berücksichtigt Section-Types + +**Logik:** +- Für jede Section: Ermittle `effectiveType` +- Für Links zwischen Sections: Verwende `effectiveType` für Edge-Type-Vorschläge +- Schema-Lookup: `getTopologyInfo(sourceSectionType, targetSectionType)` + +**Kompatibilität:** +- Bestehende Semantic Mappings funktionieren unverändert +- Section-Types werden zusätzlich berücksichtigt + +--- + +### 3.4 Phase 4: Validierung & Linting + +#### FA-PL-10: Lint-Regeln für Section-Types + +**Anforderung:** Neue Lint-Regeln für Section-Types. + +**Neue Datei:** +- `src/lint/rules/rule_section_type.ts` + +**Regeln:** +1. **Section-Type-Validität:** Section-Type muss in `types.yaml` existieren +2. **Block-ID-Eindeutigkeit:** Block-IDs müssen innerhalb einer Note eindeutig sein +3. **Intra-Note-Edge-Validität:** Intra-Note-Edges müssen gegen `graph_schema.md` validiert werden + +**Implementierung:** +```typescript +export interface SectionTypeLintRule { + checkSectionType(section: NoteSection, types: string[]): LintFinding[]; + checkBlockIdUniqueness(sections: NoteSection[]): LintFinding[]; + checkIntraNoteEdge(edge: ParsedEdge, schema: GraphSchema): LintFinding[]; +} +``` + +**Kompatibilität:** +- Bestehende Lint-Regeln bleiben unverändert +- Neue Regeln sind optional (können deaktiviert werden) + +--- + +#### FA-PL-11: Schema-Validierung für Intra-Note-Edges + +**Anforderung:** Validierung von Intra-Note-Edges gegen `graph_schema.md`. + +**Betroffene Dateien:** +- `src/schema/GraphSchemaLoader.ts` (erweitern) +- `src/mapping/schemaHelper.ts` (erweitern) + +**Implementierung:** +1. Schema-Loader lädt "prohibited" Edges aus `graph_schema.md` +2. Schema-Helper prüft Edge gegen Schema +3. Lint-Engine zeigt Warnungen für prohibited Edges + +**Logik:** +- Für Intra-Note-Edge: `sourceSectionType -> targetSectionType` +- Prüfe gegen Schema: `getTopologyInfo(sourceType, targetType)` +- Wenn Edge in "prohibited": Warnung +- Wenn Edge nicht in "typical": Info-Hinweis + +**Kompatibilität:** +- Bestehende Schema-Validierung bleibt unverändert +- Neue Validierung ist zusätzlich + +--- + +### 3.5 Phase 5: Commands + +#### FA-PL-12: Neue Commands + +**Anforderung:** Neue Commands für WP-26 Features. + +**Betroffene Dateien:** +- `src/main.ts` (erweitern) + +**Neue Commands:** +1. **"Mindnet: Add Section Type"** + - Öffnet Section-Type-Modal + - Fügt `[!section]` Callout ein + +2. **"Mindnet: Add Block ID to Heading"** + - Generiert Block-ID für aktuelles Heading + - Fügt `^block-id` zu Heading hinzu + +3. **"Mindnet: Insert Intra-Note Edge"** + - Öffnet Edge-Type-Chooser mit Section-Type-Support + - Erstellt Intra-Note-Link mit Block-Reference + +4. **"Mindnet: Validate Section Types"** + - Führt Section-Type-Lint-Regeln aus + - Zeigt Findings in Console + +**Kompatibilität:** +- Bestehende Commands bleiben unverändert +- Neue Commands sind zusätzlich + +--- + +### 3.6 Phase 6: Dictionary-Integration + +#### FA-PL-13: Types-Loader + +**Anforderung:** Laden und Validierung von `types.yaml`. + +**Neue Datei:** +- `src/dictionary/TypesLoader.ts` + +**Funktionalität:** +1. Lädt `types.yaml` aus konfiguriertem Pfad +2. Parst verfügbare Note-Types und Section-Types +3. Validiert Section-Types in Notes gegen geladene Types +4. Live-Reload bei Änderungen (wie andere Dictionary-Dateien) + +**Interface:** +```typescript +export interface TypesConfig { + types: { + [key: string]: { + name: string; + description?: string; + // ... weitere Felder + }; + }; +} + +export class TypesLoader { + static async load(app: App, path: string): Promise; + static validateSectionType(type: string, config: TypesConfig): boolean; +} +``` + +**Kompatibilität:** +- Bestehende Dictionary-Loader bleiben unverändert +- Types-Loader ist zusätzlich + +--- + +## 4. Technische Spezifikationen + +### 4.1 TypeScript-Interfaces + +#### 4.1.1 Erweiterte Interfaces + +**NoteSection (erweitert):** +```typescript +export interface NoteSection { + heading: string | null; + headingLevel: number; + content: string; + startLine: number; + endLine: number; + links: string[]; + sectionType: string | null; // NEU + blockId: string | null; // NEU +} +``` + +**ParsedEdge (erweitert):** +```typescript +export interface ParsedEdge { + rawType: string; + targets: string[]; + lineStart: number; + lineEnd: number; + isInternal: boolean; // NEU + blockId: string | null; // NEU +} +``` + +**InterviewStep (erweitert):** +```typescript +export interface CaptureTextStep { + // ... bestehende Felder ... + sectionType?: string; // NEU: Optionaler Section-Type + blockId?: string; // NEU: Explizite Block-ID + generateBlockId?: boolean; // NEU: Automatische Block-ID-Generierung + references?: Array<{ // NEU: Referenzen zu vorherigen Sections + blockId: string; + edgeType?: string; // Optional: Vorgeschlagener Edge-Type + }>; +} + +// Gilt auch für andere Step-Types mit Section-Output: +export interface CaptureTextLineStep { + // ... bestehende Felder ... + sectionType?: string; + blockId?: string; + generateBlockId?: boolean; + references?: Array<{ blockId: string; edgeType?: string }>; +} +``` + +**WizardState (erweitert):** +```typescript +export interface WizardState { + // ... bestehende Felder ... + generatedBlockIds: Map; + sectionSequence: Array<{ // NEU: Sequenz aller Sections für Edge-Vorschläge + stepKey: string; + blockId: string | null; + sectionType: string | null; + noteType: string; // Fallback für effective_type + }>; +} +``` + +--- + +### 4.2 Regex-Patterns + +**Section-Type-Callout:** +```typescript +const SECTION_CALLOUT_RE = /^\s*>\s*\[!section\]\s*(\w+)/i; +``` + +**Block-ID in Heading:** +```typescript +const BLOCK_ID_RE = /^#{1,6}\s+(.+?)\s+\^([a-zA-Z0-9_-]+)$/; +``` + +**Block-Reference in Link:** +```typescript +const BLOCK_REFERENCE_RE = /\[\[#\^([a-zA-Z0-9_-]+)\]\]/; +``` + +### 4.3 Formatierungsregeln + +**Wichtig:** Die folgenden Formatierungsregeln müssen bei der Generierung von Markdown eingehalten werden: + +1. **Section-Type-Callout Position:** + - `> [!section] ` steht **immer direkt nach der Heading-Zeile** + - Vor dem Section-Content (Text der Sektion) + - Format: `## Heading ^block-id\n> [!section] type\n\nContent...` + +2. **Edge-Callout Position:** + - `> [!edge] ` steht **immer am Ende der Sektion** + - Nach dem Section-Content (wie bisher) + - Format: `Content...\n\n> [!edge] type\n> [[#^block-id]]` + +3. **Konsistenz:** + - Diese Regeln gelten für alle generierten Markdown-Formate (Interview-Wizard, Semantic Mapping, etc.) + - Bestehende Edge-Positionierung bleibt unverändert (am Ende der Sektion) + - Neue Section-Type-Positionierung (direkt nach Heading) ist konsistent mit Backend-Erwartungen + +--- + +### 4.3 Settings-Erweiterungen + +**Neue Settings (optional):** +```typescript +export interface MindnetSettings { + // ... bestehende Settings ... + + // WP-26 Settings + typesPath: string; // Pfad zu types.yaml + autoGenerateBlockIds: boolean; // Automatische Block-ID-Generierung + sectionTypeValidation: boolean; // Section-Type-Validierung aktivieren +} +``` + +**Kompatibilität:** +- Bestehende Settings bleiben unverändert +- Neue Settings haben Default-Werte + +--- + +## 5. Kompatibilitäts-Anforderungen + +### 5.1 Abwärtskompatibilität + +**Grundsatz:** Alle bestehenden Funktionen müssen weiterhin funktionieren. + +**Konkret:** +1. **Notes ohne Section-Types:** Funktionieren unverändert, `sectionType = null` +2. **Notes ohne Block-IDs:** Funktionieren unverändert, `blockId = null` +3. **Bestehende Commands:** Funktionieren unverändert +4. **Bestehende UI-Modals:** Funktionieren unverändert +5. **Bestehende Lint-Regeln:** Funktionieren unverändert + +--- + +### 5.2 Feature-Flags (Optional) + +**Für schrittweise Einführung:** +```typescript +export interface WP26FeatureFlags { + enableSectionTypes: boolean; // Default: true + enableBlockIds: boolean; // Default: true + enableIntraNoteEdges: boolean; // Default: true + enableSectionTypeValidation: boolean; // Default: false (Phase 4) +} +``` + +**Kompatibilität:** +- Features können einzeln aktiviert/deaktiviert werden +- Default: Alle Features aktiviert + +--- + +## 6. Test-Anforderungen + +### 6.1 Unit-Tests + +**Neue Test-Dateien:** +- `tests/sectionParser.test.ts` +- `tests/sectionTypeModal.test.ts` +- `tests/typesLoader.test.ts` + +**Bestehende Tests erweitern:** +- `tests/parseEdgesFromCallouts.test.ts` (Intra-Note-Links) +- `tests/edgeTypeChooser.test.ts` (Section-Type-Support) +- `tests/interviewRenderer.test.ts` (Section-Type-Generierung) + +--- + +### 6.2 Integration-Tests + +**Test-Szenarien:** +1. Note mit Section-Types parsen +2. Block-IDs extrahieren +3. Intra-Note-Edges erkennen +4. Section-Type-Validierung +5. Chain-Matching mit Section-Types + +--- + +## 7. Implementierungsreihenfolge + +### Phase 1: Grundlagen (Kern-Parsing) +- FA-PL-01: Section-Type-Callout-Parsing +- FA-PL-02: Block-ID-Extraktion +- FA-PL-03: Intra-Note-Link-Erkennung + +### Phase 2: UI-Komponenten +- FA-PL-04: Section-Type-Modal +- FA-PL-05: Edge-Type-Chooser mit Section-Type-Support +- FA-PL-06: Link-Prompt mit Block-ID-Generierung + +### Phase 3: Feature-Integration +- FA-PL-07: Interview-Wizard mit Section-Types, Block-IDs und automatischen Edge-Vorschlägen +- FA-PL-08: Chain Workbench mit Section-Types +- FA-PL-09: Semantic Mapping mit Section-Types + +### Phase 4: Validierung & Linting +- FA-PL-10: Lint-Regeln für Section-Types +- FA-PL-11: Schema-Validierung für Intra-Note-Edges + +### Phase 5: Commands +- FA-PL-12: Neue Commands + +### Phase 6: Dictionary-Integration +- FA-PL-13: Types-Loader + +--- + +## 8. Risiken und Mitigation + +### 8.1 Risiken + +| Risiko | Wahrscheinlichkeit | Impact | Mitigation | +|--------|-------------------|--------|------------| +| Breaking Changes in bestehenden Funktionen | Niedrig | Hoch | Umfassende Tests, Feature-Flags | +| Performance-Impact durch zusätzliches Parsing | Mittel | Mittel | Lazy Loading, Caching | +| Inkonsistenz zwischen Plugin und Backend | Mittel | Hoch | Strikte Einhaltung der Backend-Spezifikation | +| Komplexität der UI-Integration | Mittel | Mittel | Schrittweise Implementierung, klare Interfaces | + +--- + +## 9. Erfolgskriterien + +### 9.1 Funktionale Kriterien + +- ✅ Alle bestehenden Funktionen funktionieren unverändert +- ✅ Section-Types werden korrekt erkannt und geparst +- ✅ Block-IDs werden korrekt extrahiert +- ✅ Intra-Note-Edges werden korrekt erkannt +- ✅ UI-Komponenten unterstützen Section-Types +- ✅ Lint-Regeln validieren Section-Types + +### 9.2 Qualitätskriterien + +- ✅ Keine Breaking Changes +- ✅ Vollständige Abwärtskompatibilität +- ✅ Konsistente UX +- ✅ Umfassende Test-Abdeckung + +--- + +## 10. Anhänge + +### 10.1 Referenzen + +- Backend Lastenheft: `docs/06_Roadmap/06_LH_Section_Types_Intra_Note_Edges.md` (v1.3) +- Backend Plugin Interface: `docs/WP26_Plugin_Interface_Specification.md` +- Backend Implementation Checklist: `docs/WP26_Implementation_Checklist.md` + +### 10.2 Glossar + +Siehe Backend Lastenheft Kapitel 1.3. + +--- + +**Ende des Lastenhefts** diff --git a/docs/WP26_Implementation_Checklist.md b/docs/WP26_Implementation_Checklist.md new file mode 100644 index 0000000..b62d0b3 --- /dev/null +++ b/docs/WP26_Implementation_Checklist.md @@ -0,0 +1,358 @@ +# WP-26 Implementierungs-Checkliste für mindnet_obsidian Plugin + +**Version:** 1.0 +**Datum:** 25. Januar 2026 +**Status:** Implementierungsleitfaden +**Basis:** [WP26_Plugin_Interface_Specification.md](./WP26_Plugin_Interface_Specification.md) + +--- + +## Übersicht + +Diese Checkliste dient als Implementierungsleitfaden für die Integration von WP-26 Features (Section Types & Intra-Note-Edges) in das mindnet_obsidian Plugin. + +**Referenz:** Vollständige Spezifikation siehe `WP26_Plugin_Interface_Specification.md` + +--- + +## Phase 1: Grundlagen (Kern-Parsing) + +### ✅ 1.1 Section-Type-Parsing + +**Datei:** `src/mapping/sectionParser.ts` + +**Tasks:** +- [ ] Funktion `extractSectionType(content: string): string | null` hinzufügen + - Regex: `/^\s*>\s*\[!section\]\s*(\w+)/` + - Suche in gesamter Section (nicht nur direkt nach Heading) +- [ ] Funktion `extractBlockId(heading: string): string | null` hinzufügen + - Regex: `/\^([a-zA-Z0-9_-]+)/` +- [ ] Interface `NoteSection` erweitern: + ```typescript + sectionType?: string; + blockId?: string; + ``` +- [ ] `splitIntoSections()` erweitern: + - Extrahiere Section-Type aus Content + - Extrahiere Block-ID aus Heading + - Propagiere Section-Type retroaktiv zur Überschrift + +**Tests:** +- [ ] `src/tests/mapping/sectionTypeParser.test.ts` erstellen +- [ ] Test: Section-Type an beliebiger Stelle in Section +- [ ] Test: Block-ID-Extraktion aus Heading +- [ ] Test: Retroaktive Propagation + +--- + +### ✅ 1.2 Edge-Parsing-Erweiterung + +**Datei:** `src/parser/parseEdgesFromCallouts.ts` + +**Tasks:** +- [ ] Funktion `extractBlockId(link: string): string | null` hinzufügen + - Erkenne `[[#^block-id]]` + - Erkenne `[[#Section Name ^block-id]]` → extrahiere nur `block-id` +- [ ] Interface `ParsedEdge` erweitern: + ```typescript + isInternal?: boolean; + blockIds?: string[]; + ``` +- [ ] `parseEdgesFromCallouts()` erweitern: + - Extrahiere Block-IDs aus Targets + - Setze `isInternal: true` wenn alle Targets Block-IDs sind + +**Tests:** +- [ ] `src/tests/parser/parseEdgesFromCallouts.test.ts` erweitern +- [ ] Test: Block-ID-Extraktion aus `[[#^block-id]]` +- [ ] Test: Block-ID-Extraktion aus `[[#Section ^block-id]]` +- [ ] Test: `isInternal` Flag für Intra-Note-Edges + +--- + +### ✅ 1.3 Graph-Schema-Loader + +**Datei:** `src/schema/GraphSchemaLoader.ts` (NEU) + +**Tasks:** +- [ ] Klasse `GraphSchemaLoader` erstellen (analog zu `ChainRolesLoader.ts`) +- [ ] Parse `Dictionary/graph_schema.md`: + - Format: `## Source: \`type\`` + - Tabelle: `| Target | Typical | Prohibited |` +- [ ] Funktion `loadGraphSchema(): GraphSchema` implementieren +- [ ] Funktion `getTypicalEdgeFor(sourceType, targetType): string | null` implementieren +- [ ] Funktion `getTopologyInfo(sourceType, targetType): {typical, prohibited}` implementieren +- [ ] Fallback-Logik: exact → "any" → "default" + +**Tests:** +- [ ] `src/tests/schema/graphSchemaLoader.test.ts` erstellen +- [ ] Test: Schema-Loading +- [ ] Test: Typical Edge Lookup +- [ ] Test: Fallback-Logik + +--- + +## Phase 2: UI-Komponenten + +### ✅ 2.1 Section-Type-Modal + +**Datei:** `src/ui/SectionTypeModal.ts` (NEU) + +**Tasks:** +- [ ] Modal-Komponente erstellen +- [ ] Type-Auswahl aus `types.yaml` (via `DictionaryLoader`) +- [ ] Block-ID-Generierung/-Bearbeitung +- [ ] Vorschau: Wie wird es im Backend interpretiert? +- [ ] Integration in Commands + +**UI-Features:** +- [ ] Dropdown für Section-Type-Auswahl +- [ ] Input-Feld für Block-ID (mit Auto-Generierung) +- [ ] Vorschau-Panel +- [ ] Save/Cancel Buttons + +--- + +### ✅ 2.2 Block-ID-Autovervollständigung + +**Datei:** `src/ui/LinkPromptModal.ts` (ERWEITERN) + +**Tasks:** +- [ ] Block-ID-Suggestions hinzufügen +- [ ] Format: `[[#^block-id]]` mit Heading-Vorschau +- [ ] Filterung nach Section-Type (optional) +- [ ] Integration in Edge-Editing-Flows + +**UI-Features:** +- [ ] Autovervollständigung für Block-IDs +- [ ] Zeige Heading + Section-Type in Vorschau +- [ ] Unterscheidung: Intra-Note vs. Inter-Note Links + +--- + +### ✅ 2.3 Edge-Type-Chooser-Erweiterung + +**Datei:** `src/ui/EdgeTypeChooserModal.ts` (ERWEITERN) + +**Tasks:** +- [ ] Section-Type-basierte Vorschläge integrieren +- [ ] Schema-Validierung (Visual Feedback) +- [ ] Nutze `GraphSchemaLoader` für Vorschläge +- [ ] Zeige Warnungen bei "prohibited" Edges + +**UI-Features:** +- [ ] ✅ Typisch (grün) +- [ ] ⚠️ Atypisch (gelb) +- [ ] ❌ Verboten (rot) +- [ ] Vorschläge basierend auf Source/Target Section-Types + +--- + +## Phase 3: Feature-Integration + +### ✅ 3.1 Interview-Wizard-Integration + +**Dateien:** +- `src/interview/types.ts` +- `src/interview/renderer.ts` +- `src/interview/wizardState.ts` + +**Tasks:** +- [ ] `CaptureTextStep` erweitern: + ```typescript + sectionType?: string; + output?: { + includeSectionCallout?: boolean; + }; + ``` +- [ ] `CaptureTextLineStep` erweitern: + ```typescript + output?: { + generateBlockId?: boolean; + blockIdFromKey?: boolean; + }; + ``` +- [ ] `renderer.ts` erweitern: + - Funktion `renderSectionWithType()` hinzufügen + - Automatische `[!section]` Callout-Einfügung + - Automatische Block-ID-Generierung + +**Tests:** +- [ ] `src/tests/interview/renderer.test.ts` erweitern +- [ ] Test: Section-Type-Rendering +- [ ] Test: Block-ID-Generierung + +--- + +### ✅ 3.2 Chain-Workbench-Integration + +**Dateien:** +- `src/workbench/types.ts` +- `src/workbench/todoGenerator.ts` +- `src/analysis/chainInspector.ts` + +**Tasks:** +- [ ] `WorkbenchMatch` erweitern: + ```typescript + sectionTypes?: Map; + ``` +- [ ] `MissingLinkTodo` erweitern: + ```typescript + fromSectionType?: string; + toSectionType?: string; + ``` +- [ ] `todoGenerator.ts` erweitern: + - Berücksichtige Section-Types bei Edge-Type-Vorschlägen + - Nutze `graph_schema.md` für Vorschläge +- [ ] `chainInspector.ts` erweitern: + - Erkenne Intra-Note-Edges + - Nutze Section-Types für besseres Matching + +**Tests:** +- [ ] `src/tests/workbench/todoGenerator.test.ts` erweitern +- [ ] Test: Section-Type-basierte Vorschläge + +--- + +### ✅ 3.3 Mapping-Integration + +**Dateien:** +- `src/mapping/mappingBuilder.ts` +- `src/mapping/semanticMappingBuilder.ts` +- `src/mapping/updateMappingBlocks.ts` + +**Tasks:** +- [ ] `MappingContext` erweitern: + ```typescript + sectionTypes: Map; + blockIds: Map; + ``` +- [ ] Funktion `generateIntraNoteEdges()` hinzufügen: + - Generiere automatische Edges zwischen Sections + - Nutze `graph_schema.md` für Default-Edge-Types + - Nur wenn keine expliziten Edges vorhanden + +**Tests:** +- [ ] `src/tests/mapping/mappingBuilder.test.ts` erweitern +- [ ] Test: Automatische Intra-Note-Edge-Generierung + +--- + +## Phase 4: Validierung & Linting + +### ✅ 4.1 Lint-Rules + +**Dateien:** `src/lint/rules/` (NEU) + +**Tasks:** + +#### 4.1.1 Section-Type-Validierung +- [ ] `rule_section_type.ts` erstellen +- [ ] Prüfe: Section-Type muss in `types.yaml` existieren +- [ ] Warnung: Fehlende Block-IDs für referenzierte Sections +- [ ] Warnung: Section-Types ohne explizite Edges + +#### 4.1.2 Edge-Validierung +- [ ] `rule_unkown_edge.ts` erweitern +- [ ] Prüfe: Edge-Types gegen `graph_schema.md` (prohibited) +- [ ] Warnung: Atypische Edges (nicht in "typical") + +#### 4.1.3 Block-ID-Validierung +- [ ] `rule_block_id.ts` erstellen +- [ ] Warnung: Fehlende Block-IDs für referenzierte Sections +- [ ] Warnung: Doppelte Block-IDs innerhalb einer Note +- [ ] Warnung: Unbenutzte Block-IDs + +**Tests:** +- [ ] `src/tests/lint/rules/rule_section_type.test.ts` erstellen +- [ ] `src/tests/lint/rules/rule_block_id.test.ts` erstellen + +--- + +### ✅ 4.2 Vault-Triage-Erweiterung + +**Dateien:** +- `src/workbench/vaultTriageScan.ts` +- `src/commands/vaultTriageScanCommand.ts` + +**Tasks:** +- [ ] Erkenne Notes ohne Section-Types +- [ ] Erkenne fehlende Block-IDs bei referenzierten Sections +- [ ] Erkenne Intra-Note-Edges, die noch nicht explizit sind +- [ ] Zeige Verbesserungsvorschläge + +--- + +## Phase 5: Commands + +### ✅ 5.1 Neue Commands + +**Datei:** `src/main.ts` (Command-Registrierung) + +**Tasks:** + +#### 5.1.1 "Add Section Type" +- [ ] Command-ID: `mindnet:add-section-type` +- [ ] Öffne `SectionTypeModal` +- [ ] Füge `[!section]` Callout zur aktuellen Section hinzu +- [ ] Generiere Block-ID falls nicht vorhanden + +#### 5.1.2 "Add Block ID to Heading" +- [ ] Command-ID: `mindnet:add-block-id` +- [ ] Füge Block-ID zur aktuellen Überschrift hinzu +- [ ] Generiere ID aus Heading-Text (slugified) + +#### 5.1.3 "Insert Intra-Note Edge" +- [ ] Command-ID: `mindnet:insert-intra-note-edge` +- [ ] Füge `[!edge]` Callout mit Block-Reference hinzu +- [ ] Zeige Autovervollständigung für Block-IDs + +--- + +## Phase 6: Dokumentation + +### ✅ 6.1 Benutzerhandbuch + +**Datei:** `docs/01_Benutzerhandbuch.md` + +**Tasks:** +- [ ] Abschnitt "Section Types" hinzufügen +- [ ] Abschnitt "Intra-Note-Edges" hinzufügen +- [ ] Abschnitt "Block-IDs" hinzufügen +- [ ] Quick-Start-Guide für WP-26 Features + +--- + +### ✅ 6.2 Entwicklerhandbuch + +**Datei:** `docs/03_Entwicklerhandbuch.md` + +**Tasks:** +- [ ] Abschnitt "WP-26 Integration" hinzufügen +- [ ] API-Referenz für neue Funktionen +- [ ] Beispiele für Section-Type-Parsing + +--- + +## Zusammenfassung + +| Phase | Komponenten | Status | +|-------|-------------|--------| +| **Phase 1** | Section-Parsing, Edge-Parsing, Schema-Loader | ⏳ Offen | +| **Phase 2** | Section-Type-Modal, Block-ID-Autocomplete, Edge-Chooser | ⏳ Offen | +| **Phase 3** | Interview, Chain-Workbench, Mapping | ⏳ Offen | +| **Phase 4** | Lint-Rules, Vault-Triage | ⏳ Offen | +| **Phase 5** | Commands | ⏳ Offen | +| **Phase 6** | Dokumentation | ⏳ Offen | + +--- + +## Nächste Schritte + +1. **Review der Spezifikation** (`WP26_Plugin_Interface_Specification.md`) +2. **Priorisierung:** Welche Phase zuerst? +3. **Start mit Phase 1:** Grundlagen (Parsing & Schema-Loader) + +--- + +**Ende der Checkliste** diff --git a/docs/WP26_Plugin_Interface_Specification.md b/docs/WP26_Plugin_Interface_Specification.md new file mode 100644 index 0000000..1482962 --- /dev/null +++ b/docs/WP26_Plugin_Interface_Specification.md @@ -0,0 +1,797 @@ +# WP-26 Plugin-Schnittstellenspezifikation + +**Version:** 1.0 +**Datum:** 25. Januar 2026 +**Status:** Implementierungsleitfaden für mindnet_obsidian Plugin +**Basis:** Lastenheft WP-26 v1.3 (Section Types & Intra-Note-Edges) + +--- + +## 1. Überblick + +Diese Spezifikation definiert die **Schnittstelle zwischen dem mindnet-Backend und dem Obsidian-Plugin** für WP-26 Features. Sie beschreibt: + +1. **Backend-Erwartungen:** Welche Markdown-Formate das Backend interpretiert +2. **Plugin-Anforderungen:** Was das Plugin implementieren muss +3. **Betroffene Bereiche:** Interview, Editing, Chain Workbench, Edge Parsing, etc. + +--- + +## 2. Backend-Schnittstelle (Markdown-Formate) + +### 2.1 Section-Type-Callout (`[!section]`) + +**Syntax:** +```markdown +## Überschrift ^block-id +> [!section] type-name +``` + +**Backend-Interpretation:** +- Callout kann **an beliebiger Stelle** innerhalb der Section stehen +- Section-Type gilt **retroaktiv** ab der Überschrift +- Scope endet bei nächster Überschrift **gleicher oder höherer Ebene** +- Fallback: Wenn kein `[!section]` vorhanden → `note_type` wird verwendet + +**Valide Types:** Müssen in `types.yaml` definiert sein (z.B. `experience`, `insight`, `decision`, `value`, `event`) + +**Beispiele:** +```markdown +## Situation ^sit +> [!section] experience + +Text der Situation... + +## Reflexion ^ref +> [!section] insight + +Text der Reflexion... +``` + +--- + +### 2.2 Edge-Callout (`[!edge]`) + +**Syntax (einfach):** +```markdown +> [!edge] edge-kind +> [[Target]] +> [[Target#Section]] +> [[#^block-id]] +``` + +**Syntax (verschachtelt):** +```markdown +> [!abstract] Semantic Edges +>> [!edge] derives +>> [[#^sit]] +>> [[#^react]] +> +>> [!edge] supports +>> [[Externe Note]] +``` + +**Backend-Interpretation:** +- Verschachtelte Callouts werden korrekt erkannt +- Block-References (`[[#^block-id]]`) haben Priorität vor Heading-Links (`[[#Section]]`) +- Intra-Note-Links (`[[#^id]]`) werden als `is_internal: true` markiert + +**Valide Edge-Kinds:** Aus `edge_vocabulary.md` (z.B. `caused_by`, `derives`, `solves`, `guides`, `related_to`) + +--- + +### 2.3 Block-References + +**Deklaration (in Überschrift):** +```markdown +## Überschrift ^block-id +``` + +**Referenzierung:** +```markdown +> [!edge] derives +> [[#^block-id]] +``` + +**Backend-Interpretation:** +- Block-ID wird aus Überschrift extrahiert: `^([a-zA-Z0-9_-]+)` +- Bei Referenzen wie `[[#📖 Diagnose ^kontext]]` wird nur `kontext` verwendet +- Fallback: Wenn Block-ID fehlt → Heading-Name wird verwendet + +--- + +## 3. Plugin-Anforderungen nach Bereich + +### 3.1 Edge Parsing (`src/parser/`) + +#### 3.1.1 Erweiterte Edge-Erkennung + +**Betroffene Dateien:** +- `src/parser/parseEdgesFromCallouts.ts` + +**Anforderungen:** + +1. **Block-ID-Extraktion aus Links:** + ```typescript + // Erweitere parseEdgesFromCallouts() um Block-ID-Erkennung + function extractBlockId(link: string): string | null { + // [[#^block-id]] → "block-id" + // [[#Section Name ^block-id]] → "block-id" + // [[#Section]] → null (Fallback auf Heading) + } + ``` + +2. **Intra-Note-Edge-Erkennung:** + ```typescript + interface ParsedEdge { + rawType: string; + targets: string[]; + lineStart: number; + lineEnd: number; + isInternal?: boolean; // NEU: Flag für Intra-Note-Edges + blockIds?: string[]; // NEU: Extrahierte Block-IDs + } + ``` + +**Implementierung:** +- Erkenne `[[#^block-id]]` Format +- Markiere als `isInternal: true` wenn alle Targets Block-IDs sind +- Extrahiere Block-IDs für spätere Validierung + +--- + +### 3.2 Section Parsing (`src/mapping/sectionParser.ts`) + +#### 3.2.1 Section-Type-Erkennung + +**Betroffene Dateien:** +- `src/mapping/sectionParser.ts` + +**Anforderungen:** + +1. **Section-Type-Callout-Parsing:** + ```typescript + interface NoteSection { + heading: string | null; + headingLevel: number; + content: string; + startLine: number; + endLine: number; + links: string[]; + sectionType?: string; // NEU: Aus [!section] Callout + blockId?: string; // NEU: Aus Heading ^block-id + } + ``` + +2. **Section-Type-Extraktion:** + ```typescript + function extractSectionType(content: string): string | null { + // Suche nach > [!section] type-name + // Kann an beliebiger Stelle in der Section stehen + // Gilt retroaktiv ab der Überschrift + } + ``` + +3. **Block-ID-Extraktion:** + ```typescript + function extractBlockId(heading: string): string | null { + // ## Heading ^block-id → "block-id" + // Regex: /\^([a-zA-Z0-9_-]+)/ + } + ``` + +**Implementierung:** +- Parse `[!section]` Callouts innerhalb von Sections +- Extrahiere Block-IDs aus Headings +- Propagiere Section-Type retroaktiv zur Überschrift + +--- + +### 3.3 Interview Wizard (`src/interview/`) + +#### 3.3.1 Section-Type-Unterstützung + +**Betroffene Dateien:** +- `src/interview/renderer.ts` +- `src/interview/types.ts` +- `src/interview/wizardState.ts` + +**Anforderungen:** + +1. **Section-Type-Auswahl:** + ```typescript + interface CaptureTextStep { + type: "capture_text"; + key: string; + label?: string; + required?: boolean; + section?: string; + sectionType?: string; // NEU: Vorgeschlagener Section-Type + prompt?: string; + output?: { + template?: string; + includeSectionCallout?: boolean; // NEU: Automatisch [!section] einfügen + }; + } + ``` + +2. **Automatische Block-ID-Generierung:** + ```typescript + interface CaptureTextLineStep { + type: "capture_text_line"; + // ... existing fields ... + output?: { + template?: string; + generateBlockId?: boolean; // NEU: Automatisch ^block-id generieren + blockIdFromKey?: boolean; // NEU: Block-ID aus step.key ableiten + }; + } + ``` + +3. **Rendering mit Section-Types:** + ```typescript + function renderSectionWithType( + heading: string, + sectionType: string | null, + blockId: string | null + ): string { + // Generiere: ## Heading ^block-id\n> [!section] type\n + } + ``` + +**Implementierung:** +- Erweitere Interview-Steps um Section-Type-Optionen +- Generiere automatisch Block-IDs basierend auf Step-Keys +- Füge `[!section]` Callouts automatisch ein, wenn `sectionType` definiert ist + +--- + +### 3.4 Chain Workbench (`src/workbench/`) + +#### 3.4.1 Section-Type-basierte Chain-Analyse + +**Betroffene Dateien:** +- `src/workbench/types.ts` +- `src/workbench/todoGenerator.ts` +- `src/analysis/chainInspector.ts` + +**Anforderungen:** + +1. **Section-Type in Chain-Matching:** + ```typescript + interface WorkbenchMatch extends TemplateMatch { + // ... existing fields ... + sectionTypes?: Map; // NEU: Map von Slot-ID → Section-Type + } + ``` + +2. **Section-Type-Validierung:** + ```typescript + interface MissingLinkTodo extends WorkbenchTodo { + // ... existing fields ... + fromSectionType?: string; // NEU: Section-Type der Quelle + toSectionType?: string; // NEU: Section-Type des Ziels + suggestedEdgeTypes: string[]; // Basierend auf graph_schema.md + } + ``` + +3. **Intra-Note-Edge-Erkennung:** + ```typescript + function detectIntraNoteEdges( + file: string, + sections: NoteSection[] + ): ParsedEdge[] { + // Finde alle Edges innerhalb derselben Note + // Markiere mit isInternal: true + } + ``` + +**Implementierung:** +- Berücksichtige Section-Types bei Chain-Matching +- Nutze `graph_schema.md` für Edge-Type-Vorschläge +- Erkenne Intra-Note-Edges für bessere Chain-Analyse + +--- + +### 3.5 Edge Editing (`src/ui/`) + +#### 3.5.1 Edge-Type-Chooser mit Section-Type-Awareness + +**Betroffene Dateien:** +- `src/ui/EdgeTypeChooserModal.ts` +- `src/ui/InlineEdgeTypeModal.ts` + +**Anforderungen:** + +1. **Section-Type-basierte Vorschläge:** + ```typescript + function getSuggestedEdgeTypes( + sourceSectionType: string, + targetSectionType: string + ): string[] { + // Nutze graph_schema.md für "typical" Edges + // Zeige nur relevante Edge-Types basierend auf Section-Types + } + ``` + +2. **Block-ID-Autovervollständigung:** + ```typescript + function suggestBlockIds( + currentNote: string, + query: string + ): Array<{blockId: string, heading: string, sectionType: string}> { + // Zeige verfügbare Block-IDs aus aktueller Note + // Format: "heading (sectionType) ^block-id" + } + ``` + +**Implementierung:** +- Lade `graph_schema.md` für Edge-Type-Vorschläge +- Zeige Block-IDs aus aktueller Note in Autovervollständigung +- Validiere Edge-Types gegen Schema (Warnung bei "prohibited") + +--- + +### 3.6 Mapping & Semantic Edges (`src/mapping/`) + +#### 3.6.1 Section-Type-basierte Mapping-Logik + +**Betroffene Dateien:** +- `src/mapping/mappingBuilder.ts` +- `src/mapping/semanticMappingBuilder.ts` +- `src/mapping/updateMappingBlocks.ts` + +**Anforderungen:** + +1. **Section-Type-Tracking:** + ```typescript + interface MappingContext { + // ... existing fields ... + sectionTypes: Map; // Map von Heading → Section-Type + blockIds: Map; // Map von Heading → Block-ID + } + ``` + +2. **Intra-Note-Edge-Generierung:** + ```typescript + function generateIntraNoteEdges( + sections: NoteSection[], + sectionTypes: Map + ): ParsedEdge[] { + // Generiere automatische Edges zwischen Sections + // Nutze graph_schema.md für Default-Edge-Types + // Nur wenn keine expliziten Edges vorhanden + } + ``` + +**Implementierung:** +- Tracke Section-Types während Mapping +- Generiere Default-Edges basierend auf Section-Transitions +- Nutze `graph_schema.md` für Edge-Type-Auswahl + +--- + +## 4. Dictionary-Integration + +### 4.1 graph_schema.md Parsing + +**Betroffene Dateien:** +- `src/schema/GraphSchemaLoader.ts` (neu zu erstellen) + +**Anforderungen:** + +1. **Schema-Loader:** + ```typescript + interface GraphSchema { + [sourceType: string]: { + [targetType: string]: { + typical: string[]; + prohibited: string[]; + }; + }; + } + + function loadGraphSchema(): GraphSchema { + // Parse Dictionary/graph_schema.md + // Extrahiere "typical" und "prohibited" Edge-Types + } + ``` + +2. **Typical Edge Lookup:** + ```typescript + function getTypicalEdgeFor( + sourceType: string, + targetType: string + ): string | null { + // Lookup im Schema + // Fallback-Logik: exact → "any" → "default" + } + ``` + +3. **Topology Info:** + ```typescript + function getTopologyInfo( + sourceType: string, + targetType: string + ): {typical: string[], prohibited: string[]} { + // Gibt vollständige Topology-Info zurück + } + ``` + +**Implementierung:** +- Erstelle `GraphSchemaLoader.ts` analog zu `ChainRolesLoader.ts` +- Parse `graph_schema.md` Format +- Implementiere Fallback-Logik wie im Backend + +--- + +### 4.2 types.yaml Integration + +**Anforderungen:** + +1. **Section-Type-Validierung:** + ```typescript + function validateSectionType(type: string): boolean { + // Prüfe gegen types.yaml + // Zeige Warnung bei unbekannten Types + } + ``` + +2. **Type-Autovervollständigung:** + ```typescript + function getAvailableSectionTypes(): string[] { + // Lade types.yaml + // Zeige alle verfügbaren Types für Autovervollständigung + } + ``` + +--- + +## 5. UI-Komponenten + +### 5.1 Section-Type-Editor + +**Neue Komponente:** `src/ui/SectionTypeModal.ts` + +**Funktionalität:** +- Auswahl eines Section-Types aus `types.yaml` +- Vorschau: Wie die Section im Backend interpretiert wird +- Block-ID-Generierung/-Bearbeitung + +**UI:** +```typescript +interface SectionTypeModalProps { + heading: string; + currentSectionType: string | null; + currentBlockId: string | null; + onSave: (sectionType: string | null, blockId: string | null) => void; +} +``` + +--- + +### 5.2 Block-ID-Autovervollständigung + +**Erweiterung:** `src/ui/LinkPromptModal.ts` + +**Funktionalität:** +- Zeige verfügbare Block-IDs aus aktueller Note +- Format: `[[#^block-id]]` mit Heading-Vorschau +- Filterung nach Section-Type (optional) + +--- + +### 5.3 Edge-Validierung (Visual Feedback) + +**Erweiterung:** `src/ui/EdgeTypeChooserModal.ts` + +**Funktionalität:** +- Zeige Schema-Validierung in Echtzeit +- Warnung bei "prohibited" Edges +- Vorschlag für "typical" Edges basierend auf Section-Types + +**UI-Indikatoren:** +- ✅ Typisch (grün) +- ⚠️ Atypisch (gelb) +- ❌ Verboten (rot) + +--- + +## 6. Commands + +### 6.1 Neue Commands + +#### 6.1.1 "Add Section Type" + +**Command-ID:** `mindnet:add-section-type` + +**Funktionalität:** +- Fügt `[!section]` Callout zur aktuellen Section hinzu +- Öffnet `SectionTypeModal` für Type-Auswahl +- Generiert automatisch Block-ID falls nicht vorhanden + +--- + +#### 6.1.2 "Add Block ID to Heading" + +**Command-ID:** `mindnet:add-block-id` + +**Funktionalität:** +- Fügt Block-ID zur aktuellen Überschrift hinzu +- Format: `## Heading ^block-id` +- Generiert ID aus Heading-Text (slugified) + +--- + +#### 6.1.3 "Insert Intra-Note Edge" + +**Command-ID:** `mindnet:insert-intra-note-edge` + +**Funktionalität:** +- Fügt `[!edge]` Callout mit Block-Reference hinzu +- Zeigt Autovervollständigung für Block-IDs +- Vorschläge basierend auf Section-Types + +--- + +### 6.2 Erweiterte Commands + +#### 6.2.1 Chain Workbench + +**Betroffene Dateien:** +- `src/commands/chainWorkbenchCommand.ts` + +**Erweiterungen:** +- Berücksichtige Section-Types bei Chain-Matching +- Zeige Section-Types in Match-Details +- Vorschläge für Intra-Note-Edges basierend auf Schema + +--- + +#### 6.2.2 Interview Wizard + +**Betroffene Dateien:** +- `src/interview/renderer.ts` + +**Erweiterungen:** +- Automatische Section-Type-Zuweisung basierend auf Step-Konfiguration +- Block-ID-Generierung für alle Sections +- Automatische Intra-Note-Edges zwischen Sections + +--- + +## 7. Validierung & Linting + +### 7.1 Section-Type-Validierung + +**Neue Rules:** `src/lint/rules/rule_section_type.ts` + +**Validierung:** +- Section-Type muss in `types.yaml` existieren +- Warnung bei fehlenden Block-IDs für referenzierte Sections +- Warnung bei Section-Types ohne explizite Edges (könnte Default-Edge nutzen) + +--- + +### 7.2 Edge-Validierung + +**Erweiterung:** `src/lint/rules/rule_unkown_edge.ts` + +**Validierung:** +- Prüfe Edge-Types gegen `edge_vocabulary.md` +- Prüfe Edge-Types gegen `graph_schema.md` (prohibited) +- Warnung bei atypischen Edges (nicht in "typical") + +--- + +### 7.3 Block-ID-Validierung + +**Neue Rule:** `src/lint/rules/rule_block_id.ts` + +**Validierung:** +- Warnung bei fehlenden Block-IDs für referenzierte Sections +- Warnung bei doppelten Block-IDs innerhalb einer Note +- Warnung bei Block-IDs, die nicht referenziert werden + +--- + +## 8. Integration mit bestehenden Features + +### 8.1 Vault Triage Scan + +**Betroffene Dateien:** +- `src/workbench/vaultTriageScan.ts` +- `src/commands/vaultTriageScanCommand.ts` + +**Erweiterungen:** +- Erkenne Notes ohne Section-Types (könnten von WP-26 profitieren) +- Erkenne fehlende Block-IDs bei referenzierten Sections +- Erkenne Intra-Note-Edges, die noch nicht explizit sind + +--- + +### 8.2 Chain Inspector + +**Betroffene Dateien:** +- `src/analysis/chainInspector.ts` + +**Erweiterungen:** +- Berücksichtige Section-Types bei Chain-Matching +- Nutze Section-Types für bessere Edge-Type-Vorschläge +- Erkenne Intra-Note-Chains innerhalb einer Note + +--- + +## 9. Implementierungsreihenfolge + +### Phase 1: Grundlagen (Kern-Parsing) + +1. ✅ **Section-Type-Parsing** (`sectionParser.ts`) + - `[!section]` Callout-Erkennung + - Block-ID-Extraktion aus Headings + - Section-Type-Propagation + +2. ✅ **Edge-Parsing-Erweiterung** (`parseEdgesFromCallouts.ts`) + - Block-ID-Erkennung in Links + - Intra-Note-Edge-Flag + +3. ✅ **Graph-Schema-Loader** (`GraphSchemaLoader.ts`) + - Parse `graph_schema.md` + - Implementiere Lookup-Funktionen + +--- + +### Phase 2: UI-Komponenten + +4. ✅ **Section-Type-Modal** (`SectionTypeModal.ts`) + - Type-Auswahl + - Block-ID-Generierung + +5. ✅ **Block-ID-Autovervollständigung** (Erweiterung `LinkPromptModal.ts`) + - Zeige verfügbare Block-IDs + - Filterung nach Section-Type + +6. ✅ **Edge-Type-Chooser-Erweiterung** (`EdgeTypeChooserModal.ts`) + - Section-Type-basierte Vorschläge + - Schema-Validierung (Visual Feedback) + +--- + +### Phase 3: Feature-Integration + +7. ✅ **Interview-Wizard-Integration** (`renderer.ts`) + - Section-Type-Unterstützung + - Automatische Block-ID-Generierung + +8. ✅ **Chain-Workbench-Integration** (`chainWorkbenchCommand.ts`) + - Section-Type-basierte Chain-Analyse + - Intra-Note-Edge-Erkennung + +9. ✅ **Mapping-Integration** (`mappingBuilder.ts`) + - Section-Type-Tracking + - Automatische Intra-Note-Edge-Generierung + +--- + +### Phase 4: Validierung & Linting + +10. ✅ **Lint-Rules** (`src/lint/rules/`) + - Section-Type-Validierung + - Edge-Validierung gegen Schema + - Block-ID-Validierung + +11. ✅ **Vault-Triage-Erweiterung** (`vaultTriageScan.ts`) + - WP-26-Feature-Erkennung + - Verbesserungsvorschläge + +--- + +## 10. Test-Strategie + +### 10.1 Unit-Tests + +**Neue Test-Dateien:** +- `src/tests/parser/parseSectionCallouts.test.ts` +- `src/tests/mapping/sectionTypeParser.test.ts` +- `src/tests/schema/graphSchemaLoader.test.ts` + +**Bestehende Tests erweitern:** +- `src/tests/parser/parseEdgesFromCallouts.test.ts` (Block-ID-Support) +- `src/tests/interview/renderer.test.ts` (Section-Type-Support) + +--- + +### 10.2 Integration-Tests + +**Test-Szenarien:** +1. Interview-Wizard mit Section-Types +2. Chain-Workbench mit Intra-Note-Edges +3. Edge-Editing mit Schema-Validierung + +--- + +## 11. Migration & Abwärtskompatibilität + +### 11.1 Bestehende Notes + +**Garantie:** Notes ohne `[!section]` Callouts funktionieren weiterhin: +- Fallback auf `note_type` +- Keine Breaking Changes + +### 11.2 Graduelle Migration + +**Empfehlung:** +1. Plugin zeigt Optionen für WP-26 Features +2. Nutzer kann schrittweise migrieren +3. Vault-Triage-Scan zeigt Verbesserungspotenzial + +--- + +## 12. Dokumentation für Plugin-Nutzer + +### 12.1 Quick-Start-Guide + +**Inhalt:** +- Wie füge ich Section-Types hinzu? +- Wie erstelle ich Intra-Note-Edges? +- Wie nutze ich Block-IDs? + +### 12.2 Best Practices + +**Inhalt:** +- Wann Section-Types verwenden? +- Block-ID-Namenskonventionen +- Schema-konforme Edge-Types + +--- + +## 13. Anhang: TypeScript-Interfaces + +### 13.1 Erweiterte Types + +```typescript +// src/parser/types.ts +export interface ParsedEdge { + rawType: string; + targets: string[]; + lineStart: number; + lineEnd: number; + isInternal?: boolean; // WP-26: Intra-Note-Edge-Flag + blockIds?: string[]; // WP-26: Extrahierte Block-IDs + sectionTypes?: { // WP-26: Section-Types von Source/Target + source?: string; + target?: string; + }; +} + +// src/mapping/sectionParser.ts +export interface NoteSection { + heading: string | null; + headingLevel: number; + content: string; + startLine: number; + endLine: number; + links: string[]; + sectionType?: string; // WP-26: Aus [!section] Callout + blockId?: string; // WP-26: Aus Heading ^block-id +} + +// src/schema/types.ts (neu) +export interface GraphSchema { + [sourceType: string]: { + [targetType: string]: { + typical: string[]; + prohibited: string[]; + }; + }; +} +``` + +--- + +**Ende der Spezifikation** + +**Nächste Schritte:** +1. Review der Spezifikation +2. Priorisierung der Implementierungsphasen +3. Start mit Phase 1 (Grundlagen)