refactor(markdown-parser): hardcoded link/anchor patterns to Strategy Pattern

[WesleyMFrederick]

Problem

Link and anchor extraction uses hardcoded regex patterns scattered throughout extractLinks() and extractAnchors() methods.

Patterns Currently Hardcoded

Type	Pattern	Code Location
Link	[text](file.md#anchor)	extractLinks:118
Link	[cite: path]	extractLinks:165
Link	[[file#anchor|text]]	extractLinks:266
Link	[[#anchor|text]]	extractLinks:313
Link	[text](#anchor)	extractLinks:354
Link	^anchor-id reference	extractLinks:395
Anchor	## Header Text	extractAnchors:600
Anchor	^block-id	extractAnchors:551

Proposed Solution

Refactor to Strategy Pattern (like ExtractionStrategy in ContentExtractor) for:

• Pluggable pattern registration
• Easier testing of individual patterns
• Support for custom/user-defined patterns

Priority

Low - current implementation works; refactor when adding new patterns.

---

Acceptance Criteria

• Each link/anchor pattern extracted into its own Strategy class
• Strategy registry allows adding/removing patterns without modifying core parser
• All existing link types detected identically to current implementation
• Individual strategies are independently testable
• No regression in extraction accuracy or performance

Definition of Done

• Snapshot tests written: current extraction output captured for all pattern types (RED phase)
• Strategy interface defined and individual strategies implemented (GREEN phase)
• Snapshot tests pass with identical output post-refactor
• All existing citation-manager tests pass
• Build succeeds: npm run build -w tools/citation-manager && npm link -w tools/citation-manager
• No measurable performance regression on large files
• Committed with conventional commit message referencing this issue

[WesleyMFrederick]

Architecture Discussion: Markdown Flavor Strategies (2025-12-01)

Expanded Vision: Beyond Pattern Refactoring

The original issue focuses on making patterns pluggable. After deeper analysis, a more powerful architecture emerges: flavor-aware parsing and validation across markdown tools.

The Problem: Same Header, Different Anchors

Tool	Header: ## My Header	Link Syntax
Obsidian wikilink	[[Note#My Header]]	Raw spaces OK
Obsidian markdown	[Text](Note.md#My%20Header)	URL-encoded
GitHub	[Text](#my-header)	Auto-kebab

Same semantic target, 3 different anchor formats. Current parser doesn't know which format to expect or validate against.

Proposed Architecture: Flavor Strategies + Plugin Bundles

┌─────────────────────────────────────────────────────┐
│  User Config: ["obsidian", "github"]                │
├─────────────────────────────────────────────────────┤
│                                                     │
│  Plugin Bundle (auto-composed from config)          │
│  ┌─────────────────┐ ┌─────────────────┐           │
│  │ ObsidianFlavor  │ │  GitHubFlavor   │           │
│  │ Strategy        │ │  Strategy       │           │
│  └─────────────────┘ └─────────────────┘           │
│                                                     │
│  Validation = INTERSECTION of what both support     │
│                                                     │
│  Output: "⚠️ This wikilink won't work in GitHub"   │
└─────────────────────────────────────────────────────┘

Strategy Interface (Sketch)

interface FlavorStrategy {
  readonly flavor: string;  // "obsidian" | "github" | "commonmark" etc.
  
  // Anchor extraction
  readonly anchorPatterns: RegExp[];
  extractAnchor(line: string, index: number): AnchorObject | null;
  normalizeAnchorId(raw: string): string;  // URL-encode, kebab-case, etc.
  
  // Link extraction  
  readonly linkPatterns: RegExp[];
  extractLink(match: RegExpMatchArray): LinkObject | null;
  
  // Portability validation
  isPortableTo(other: FlavorStrategy): boolean;
  getPortabilityWarnings(link: LinkObject, targetFlavors: FlavorStrategy[]): string[];
}

class CommonMarkStrategy implements FlavorStrategy { /* base */ }
class ObsidianStrategy extends CommonMarkStrategy { /* adds wikilinks, ^blockid */ }
class GitHubStrategy extends CommonMarkStrategy { /* auto-kebab headers */ }

Where This Fits in Current Architecture

1. MarkdownParser Layer 2 (currently hardcoded regex)

   • Replace with FlavorStrategy[] injection via constructor
   • Each strategy handles its patterns

2. CitationValidator

   • Already validates file + anchor existence
   • Add: validate against configured tool intersection
   • Warn: "This link pattern won't work in GitHub"

3. ContentExtractor eligibility

   • Could add PortabilityStrategy to skip non-portable links

Research Gap: URL Encoding

The Markdown Link Flavors research doc needs expansion:

• Obsidian wikilink header normalization (spaces → raw, colons removed)
• Obsidian markdown link encoding (spaces → %20)
• GitHub auto-kebab rules (spaces → -, case insensitive)
• How these interact with special characters (/, :, etc.)

Implementation Phases

Phase 1: Extract current patterns into CommonMarkStrategy + ObsidianStrategy

• No behavior change, just refactor to strategy interface
• Validates pattern works before expanding

Phase 2: Add flavor config to CLI

• --flavors obsidian,github flag
• Config file support

Phase 3: Cross-tool validation

• Compute intersection of supported patterns
• Warn on non-portable syntax

Phase 4: Plugin system

• User-defined strategies
• npm package distribution?

Related Issues

• Hardcoded Extraction Marker Detection (MVP Tech Debt) cc-workflows#32 - Hardcoded Extraction Marker Detection (same pattern)
• Refactor MarkdownParser.ts: Break Down Monolithic File Using Action-Based Patterns cc-workflows#18 - Monolithic file structure (would reorganize with strategies)
• (tool/citation-manager) [Bug]: Header anchor matching fails for headings with Obsidian invalid characters (colons) cc-workflows#1 - Obsidian invalid characters (flavor-specific normalization)

References

• ContentExtractor eligibility strategies: src/core/ContentExtractor/eligibilityStrategies/
• Micromark Obsidian extensions: @moritzrs/micromark-extension-ofm-wikilink
• Markdownlint approach: token-based with selective regex (documented in parser guide whiteboard)