Incomplete Facade Encapsulation for Advanced Queries

[WesleyMFrederick]

Problem

CitationValidator helper methods require direct _data.anchors access for metadata-dependent operations, breaking facade encapsulation.

Affected Code Locations

• Line 528: suggestObsidianBetterFormat() needs anchor objects with anchorType and rawText properties
• Line 560: findFlexibleAnchorMatch() needs anchor objects with rawText for markdown-aware matching
• Lines 570-578: Suggestion generation needs anchor objects filtered by type

Missing Facade Methods

// Needed: Return full anchor object with metadata
getAnchorByIdWithMetadata(anchorId: string): AnchorObject | null

Current Workaround

Helper methods access parsedDoc._data.anchors directly:

// Current approach - breaks encapsulation
const anchor = parsedDoc._data.anchors.find(a => a.id === anchorId)

Impact Assessment

Positive:

• ✅ Primary validation fully decoupled via hasAnchor() and findSimilarAnchors() methods
• ✅ Core extraction functionality works correctly

Negative:

• ❌ Error reporting and advanced matching still coupled to internal anchor schema
• ❌ Violates facade pattern encapsulation principle
• ❌ Future changes to anchor schema may require CitationValidator updates

Recommended Solution

Extend ParsedDocument facade with metadata-aware query methods:

class ParsedDocument {
  // Return full anchor object with all metadata
  getAnchorByIdWithMetadata(anchorId: string): AnchorObject | null {
    return this._data.anchors.find(a => a.id === anchorId || a.urlEncodedId === anchorId) || null
  }

  // Return anchors filtered by type
  getAnchorsByType(anchorType: 'header' | 'block'): AnchorObject[] {
    return this._data.anchors.filter(a => a.anchorType === anchorType)
  }
}

Priority Justification

Low Priority because:

1. Core functionality works correctly
2. Limited to error reporting edge cases
3. Only affects CitationValidator helper methods
4. Workaround is acceptable for MVP

Resolution Timeline

Future epic when:

• Multiple consumers need anchor metadata access
• Facade pattern violations accumulate
• Major refactoring planned for validation layer

---

Created By: US1.7 Implementation (2025-10-XX)
Status: Low-priority technical debt
Source: ParsedDocument Implementation Guide - Known Limitations