📘 Complete migration documentation for custom template users (v2.0 breaking change)

[coderabbitai]

🎯 Objective

Complete and enhance the migration documentation for users transitioning from template-based to programmatic markdown generation in v2.0. This task builds upon existing migration guides to provide comprehensive support for custom template users.

📋 Context

Related Work

• Parent Issue: Phase 3: Migrate Template Functions to Type-Safe Go Methods for Performance & Maintainability #86 - Phase 3: Port Template Functions to Go Methods
• Existing Documentation:
  • docs/migration.md - General migration guide with performance benefits and basic steps
  • docs/template-function-migration.md - Function mapping reference with migration status
• Breaking Change: Template deprecation planned for v3.0
• Current Status: Core MarkdownBuilder methods implemented, need user-facing documentation completion

Why This Matters

Custom template users need clear, actionable guidance to:

1. Understand migration urgency and timeline (template support ending v3.0)
2. Map their custom template functions to new Go methods
3. Validate migration success before production deployment
4. Contribute custom functions back to the project

Without this: Users may abandon opnDossier or face breaking changes without preparation.

🔧 Proposed Solution

1. Enhance Migration Guide (docs/migration-guide.md)

Additions to existing docs/migration.md:

A. Clear Deprecation Timeline

## ⚠️ Deprecation Timeline

- **v2.0** (Current): Template mode available via `--use-template` flag
- **v2.1-v2.5**: Template mode deprecated, warnings issued
- **v3.0**: Template mode removed entirely

**Action Required**: Migrate custom templates by v2.5 (estimated Q2 2025)

B. Custom Template User Quick Start

## For Custom Template Users

### Step 1: Assessment
Run the migration validator to identify custom functions:
\`\`\`bash
./scripts/validate-migration.sh --analyze ./your-templates/
\`\`\`

### Step 2: Map Functions
Use the function mapping table to find equivalents:
- `{{ getRiskLevel .severity }}` → `builder.AssessRiskLevel(severity)`
- See full mapping in [template-function-migration.md](./template-function-migration.md)

### Step 3: Choose Migration Path
**Option A**: Continue with templates (temporary)
\`\`\`bash
opndossier convert -i config.xml -o report.md --use-template
\`\`\`

**Option B**: Migrate to programmatic (recommended)
- Create custom builder extending MarkdownBuilder
- Port template logic to Go methods
- See examples below

C. Real-World Migration Examples

// Example 1: Custom Risk Assessment Section
type SecurityBuilder struct {
    *converter.MarkdownBuilder
}

func (b *SecurityBuilder) WriteRiskAnalysis(doc *model.OpnSenseDocument) {
    b.WriteHeader(2, "🔒 Security Risk Analysis")
    
    // Use inherited MarkdownBuilder methods
    firewallRisk := b.AssessRiskLevel(doc.Firewall.Severity)
    natRisk := b.AssessNATRuleRisk(doc.NAT.Rules)
    
    b.WriteTable([]string{"Component", "Risk Level", "Action"}, [][]string{
        {"Firewall", firewallRisk, "Review rules"},
        {"NAT", natRisk, "Audit configuration"},
    })
}

// Example 2: Custom Compliance Report
func (b *SecurityBuilder) WriteComplianceSection(doc *model.OpnSenseDocument) {
    b.WriteHeader(2, "📊 Compliance Status")
    
    for _, rule := range doc.Firewall.Rules {
        compliance := b.AssessFirewallRuleCompliance(rule)
        if compliance.IsFailing() {
            b.WriteListItem(fmt.Sprintf("❌ %s: %s", rule.Description, compliance.Recommendation))
        }
    }
}

2. Create Migration Validator Script (scripts/validate-migration.sh)

Enhanced version with actual validation:

#!/bin/bash
# Migration Validation Tool v2.0

set -e

TEMPLATE_DIR="${1:-.}"
SAMPLE_CONFIG="${2:-sample.xml}"

echo "╔════════════════════════════════════════════╗"
echo "║   opnDossier Migration Validation Tool    ║"
echo "╚════════════════════════════════════════════╝"
echo ""

# Check prerequisites
command -v opndossier >/dev/null 2>&1 || { 
    echo "❌ opndossier not found. Install with: go install github.com/EvilBit-Labs/opnDossier@latest"
    exit 1
}

# Detect custom templates
if [ -d "$TEMPLATE_DIR/templates" ]; then
    echo "✅ Custom templates detected: $TEMPLATE_DIR/templates"
    
    # Extract custom functions
    echo ""
    echo "📋 Custom template functions found:"
    grep -rho '{{ *\([a-zA-Z_][a-zA-Z0-9_]*\)' "$TEMPLATE_DIR/templates" | \
        sort -u | \
        grep -v -E '(if|range|end|define|template|with|block)' | \
        sed 's/{{ */  - /' || echo "  (none detected)"
    
    # Check for unmigrated functions
    echo ""
    echo "⚠️  Checking for functions without Go equivalents..."
    # Add validation logic here
else
    echo "ℹ️  No custom templates found in $TEMPLATE_DIR"
fi

# Generate comparison reports if sample config exists
if [ -f "$SAMPLE_CONFIG" ]; then
    echo ""
    echo "🔄 Generating comparison reports..."
    
    # Template mode
    if opndossier convert -i "$SAMPLE_CONFIG" -o /tmp/report-template.md --use-template 2>/dev/null; then
        echo "  ✅ Template mode: /tmp/report-template.md"
    else
        echo "  ⚠️  Template mode failed (expected if no templates)"
    fi
    
    # Programmatic mode
    if opndossier convert -i "$SAMPLE_CONFIG" -o /tmp/report-programmatic.md 2>/dev/null; then
        echo "  ✅ Programmatic mode: /tmp/report-programmatic.md"
    else
        echo "  ❌ Programmatic mode failed"
        exit 1
    fi
    
    # Compare outputs
    if [ -f /tmp/report-template.md ] && [ -f /tmp/report-programmatic.md ]; then
        echo ""
        echo "📊 Output comparison:"
        
        TEMPLATE_LINES=$(wc -l < /tmp/report-template.md)
        PROGRAMMATIC_LINES=$(wc -l < /tmp/report-programmatic.md)
        
        echo "  Template mode:     $TEMPLATE_LINES lines"
        echo "  Programmatic mode: $PROGRAMMATIC_LINES lines"
        echo "  Difference:        $((PROGRAMMATIC_LINES - TEMPLATE_LINES)) lines"
        
        # Generate detailed diff
        diff -u /tmp/report-template.md /tmp/report-programmatic.md > /tmp/migration-diff.txt 2>&1 || true
        echo "  Detailed diff saved to: /tmp/migration-diff.txt"
    fi
else
    echo "ℹ️  No sample config provided, skipping comparison"
fi

echo ""
echo "✅ Validation complete!"
echo ""
echo "Next Steps:"
echo "  1. Review function mappings: docs/template-function-migration.md"
echo "  2. Check detailed diff: /tmp/migration-diff.txt"
echo "  3. Follow migration guide: docs/migration.md"

3. Add Contributing Guide Section

Append to docs/migration.md:

## 🤝 Contributing Custom Functions

If you've created useful custom functions, contribute them back!

### Contribution Process
1. **Implement as MarkdownBuilder method**:
   \`\`\`go
   // File: internal/converter/markdown_custom.go
   func (b *MarkdownBuilder) MyCustomFunction(param string) string {
       // Implementation with proper error handling
       return result
   }
   \`\`\`

2. **Add comprehensive tests**:
   \`\`\`go
   // File: internal/converter/markdown_custom_test.go
   func TestMarkdownBuilder_MyCustomFunction(t *testing.T) {
       // Test cases including edge cases
   }
   \`\`\`

3. **Document in migration guide**:
   - Add to function mapping table
   - Provide usage example
   - Explain migration path from template

4. **Submit PR** with:
   - Clear description of use case
   - Before/after examples
   - Test coverage report

✅ Acceptance Criteria

Documentation

• docs/migration.md enhanced with:
  • Clear deprecation timeline (v3.0 removal)
  • Custom template user quick start section
  • 3+ real-world migration examples
  • Performance comparison data
• Function mapping table in docs/template-function-migration.md updated with all current MarkdownBuilder methods
• Contributing guide added for custom function submissions
• FAQ section addresses:
  • Template support timeline
  • Hybrid mode usage
  • Performance expectations
  • Rollback procedures

Tooling

• scripts/validate-migration.sh implemented with:
  • Custom function detection
  • Side-by-side report generation
  • Diff analysis output
  • Clear error messages and next steps
• Script tested on Linux, macOS, and Windows (Git Bash)
• Script integrated into CI for validation

Testing

• Migration examples validated with actual opnDossier builds
• Validator script tested against sample custom templates
• Documentation reviewed by 2+ team members
• User feedback incorporated from Phase 3: Migrate Template Functions to Type-Safe Go Methods for Performance & Maintainability #86 discussions

🔗 References

• Parent Issue: Phase 3: Migrate Template Functions to Type-Safe Go Methods for Performance & Maintainability #86 - Port Template Functions to Go Methods
• Related Issues: Architecture: Migrate from template-based to programmatic builder-pattern markdown generation #73 - Refactor to Programmatic Markdown Generation
• Existing Docs:
  • docs/migration.md - Base migration guide
  • docs/template-function-migration.md - Function mappings
• Implementation: internal/converter/markdown_utils.go

📅 Timeline

• Target: Complete before v2.0 release
• Dependencies: Phase 3: Migrate Template Functions to Type-Safe Go Methods for Performance & Maintainability #86 completion (MarkdownBuilder methods)
• Urgency: HIGH - Users need migration path before template deprecation

[unclesp1d3r]

@coderabbitai Enhance this issue body with additional context and a proposed solution. Improve the issue title and assign the proper labels and other metadata.

[traycerai]

Plan

Observations

The opnDossier project is transitioning from template-based to programmatic markdown generation in v2.0. Existing migration documentation (docs/migration.md and docs/template-function-migration.md) provides a solid foundation but lacks critical information for custom template users. The codebase has 30+ MarkdownBuilder methods already implemented across markdown_utils.go, markdown_security.go, markdown_transformers.go, and markdown.go. The HybridGenerator supports both modes via the --use-template flag. No scripts directory exists yet.

Approach

Enhance existing migration documentation with deprecation timeline, custom template user guidance, real-world examples, and contributing guidelines. Create a migration validator script to help users assess and validate their migration. Update the function mapping table to reflect all currently implemented MarkdownBuilder methods. This documentation-focused approach ensures custom template users have clear, actionable guidance for migrating before v3.0 template removal.

Reasoning

I explored the repository structure, read existing migration documentation files (docs/migration.md and docs/template-function-migration.md), examined the MarkdownBuilder implementation across multiple files to identify all available methods, reviewed the HybridGenerator to understand template/programmatic mode switching, and searched for existing scripts (none found). This provided complete context for the documentation enhancement task.

Proposed File Changes

📄 docs/migration.md ^(MODIFY) 🔗

References

• 📄 docs/template-function-migration.md ^(MODIFY)
• 📄 internal/converter/markdown_utils.go
• 📄 internal/converter/markdown_security.go
• 📄 internal/converter/markdown_transformers.go
• 📄 internal/markdown/hybrid_generator.go

Add four major sections to enhance the existing migration guide:

1. Deprecation Timeline Section (insert after "Why Migrate?" section, before "Migration Checklist"):

   • Add clear timeline showing v2.0 (current with --use-template flag), v2.1-v2.5 (deprecated with warnings), and v3.0 (complete removal)
   • Include estimated dates (Q2 2025 for v2.5 migration deadline)
   • Emphasize urgency with action required callout

2. Custom Template User Quick Start Section (insert after "Migration Checklist", before "Step-by-Step Migration"):

   • Add three-step assessment process: run validator, map functions, choose migration path
   • Include Option A (continue with templates temporarily using --use-template) and Option B (migrate to programmatic)
   • Reference the validator script at scripts/validate-migration.sh
   • Link to function mapping table in docs/template-function-migration.md

3. Real-World Migration Examples Section (insert after existing "Example 2: Custom Function Migration", before "Performance Validation"):

   • Add Example 3: Custom Risk Assessment Section showing SecurityBuilder extending MarkdownBuilder
   • Demonstrate usage of inherited methods like AssessRiskLevel from markdown_security.go
   • Add Example 4: Custom Compliance Report showing compliance checking with firewall rules
   • Include Example 5: Custom Network Analysis showing interface grouping and filtering
   • Each example should show complete struct definition and method implementation patterns
   • Reference actual MarkdownBuilder methods from internal/converter/markdown_utils.go, markdown_security.go, and markdown_transformers.go

4. Contributing Custom Functions Section (append at end of document, after "Next Steps"):

   • Add contribution process with four steps: implement as MarkdownBuilder method, add comprehensive tests, document in migration guide, submit PR
   • Include code structure examples showing where to add methods (internal/converter/markdown_custom.go) and tests (internal/converter/markdown_custom_test.go)
   • Specify PR requirements: clear use case description, before/after examples, test coverage report
   • Reference existing test patterns from internal/converter/markdown_utils_test.go

5. FAQ Section (insert before "Next Steps" section):

   • Add Q&A covering: template support timeline (v3.0 removal), hybrid mode usage (--use-template flag), performance expectations (74% faster, 78% less memory), rollback procedures (use --use-template flag)
   • Include troubleshooting for common migration issues
   • Reference HybridGenerator behavior from internal/markdown/hybrid_generator.go

Ensure all new sections maintain consistent markdown formatting with existing document style, use proper heading levels, include code blocks with syntax highlighting, and cross-reference other documentation files appropriately.

📄 docs/template-function-migration.md ^(MODIFY) 🔗

References

• 📄 internal/converter/markdown_utils.go
• 📄 internal/converter/markdown_security.go
• 📄 internal/converter/markdown_transformers.go
• 📄 internal/converter/markdown.go

Update the function mapping tables to reflect all currently implemented MarkdownBuilder methods:

1. Update Phase 1: Core Utility Functions table:

   • Change status of escapeTableContent from "Pending" to "Migrated" (implemented in markdown_utils.go line 13)
   • Change status of isLast from "Pending" to "Migrated" (implemented as IsLastInSlice in markdown_utils.go line 79)
   • Change status of truncateDescription from "Pending" to "Migrated" (implemented in markdown_utils.go line 57)

2. Update Phase 2: Data Transformation Functions table:

   • Change status of filterTunables from "Pending" to "Migrated" (implemented as FilterSystemTunables in markdown_transformers.go line 26)
   • Add note that it includes security prefix filtering logic

3. Update Phase 3: Security and Compliance Functions table:

   • Change status of getRiskLevel from "Pending" to "Migrated" (implemented as AssessRiskLevel in markdown_security.go line 20)
   • Add new row for calculateSecurityScore → CalculateSecurityScore(data *model.OpnSenseDocument) int with status "Migrated" (implemented in markdown_security.go line 42)
   • Add new row for assessServiceRisk → AssessServiceRisk(service model.Service) string with status "Migrated" (implemented in markdown_security.go line 91)

4. Update Phase 4: Sprig Function Replacements (High Priority) table:

   • Change status of upper, lower, trim from "Pending" to "Migrated" (implemented as ToUpper, ToLower, TrimSpace in markdown_utils.go lines 130, 135, 140)
   • Change status of default from "Pending" to "Migrated" (implemented as DefaultValue in markdown_utils.go line 93)
   • Change status of empty from "Pending" to "Migrated" (implemented as IsEmpty in markdown_utils.go line 101)

5. Add new section: Phase 5: Advanced Data Operations:

   • Create new table with migrated methods from markdown_transformers.go:
     • GroupServicesByStatus(services []model.Service) map[string][]model.Service - Status: Migrated
     • AggregatePackageStats(packages []model.Package) map[string]int - Status: Migrated
     • FilterRulesByType(rules []model.Rule, ruleType string) []model.Rule - Status: Migrated
     • ExtractUniqueValues(items []string) []string - Status: Migrated

6. Add new section: Phase 6: Report Building Methods:

   • Create new table with high-level report building methods from markdown.go:
     • BuildSystemSection(data *model.OpnSenseDocument) string - Status: Migrated
     • BuildNetworkSection(data *model.OpnSenseDocument) string - Status: Migrated
     • BuildSecuritySection(data *model.OpnSenseDocument) string - Status: Migrated
     • BuildServicesSection(data *model.OpnSenseDocument) string - Status: Migrated
     • BuildStandardReport(data *model.OpnSenseDocument) (string, error) - Status: Migrated
     • BuildComprehensiveReport(data *model.OpnSenseDocument) (string, error) - Status: Migrated

7. Update Implementation Priority section:

   • Move completed Priority 1 functions to a new "Completed" subsection
   • Update Priority 2 and 3 to reflect remaining work
   • Add note that 30+ methods are now available

8. Update Migration Complexity Assessment section:

   • Add "Completed" category listing all migrated functions
   • Update complexity estimates for remaining functions

Maintain existing table formatting, add implementation file references in notes column, and ensure all status changes are clearly marked with bold Migrated text.

📁 scripts ^(NEW) 🔗

Create a new directory to house migration and utility scripts for the opnDossier project. This directory will contain the migration validator script and potentially other automation tools in the future.

📄 scripts/validate-migration.sh ^(NEW) 🔗

References

• 📄 cmd/convert.go
• 📄 docs/migration.md ^(MODIFY)
• 📄 docs/template-function-migration.md ^(MODIFY)

Create a comprehensive bash script for migration validation with the following structure:

1. Script Header:

   • Shebang line: #!/bin/bash
   • Script description and version (v2.0)
   • Set strict error handling: set -e

2. Argument Parsing:

   • Accept two arguments: TEMPLATE_DIR (default: current directory) and SAMPLE_CONFIG (default: sample.xml)
   • Display usage information if --help flag is provided

3. Banner Display:

   • Print ASCII art banner: "opnDossier Migration Validation Tool"
   • Include version and purpose information

4. Prerequisites Check:

   • Verify opndossier command is available in PATH
   • If not found, display installation instructions: go install github.com/EvilBit-Labs/opnDossier@latest
   • Exit with error code 1 if prerequisite not met

5. Custom Template Detection:

   • Check if $TEMPLATE_DIR/templates directory exists
   • If found, display confirmation message with path
   • Extract custom template functions using grep:
     • Search for template function patterns: {{ *\([a-zA-Z_][a-zA-Z0-9_]*\)
     • Filter out Go template keywords (if, range, end, define, template, with, block)
     • Sort and display unique function names
   • If no templates found, display informational message

6. Unmigrated Function Check:

   • Cross-reference detected functions with known MarkdownBuilder methods
   • Display warning for functions without Go equivalents
   • Reference docs/template-function-migration.md for mapping details

7. Comparison Report Generation (if sample config provided):

   • Generate template mode report:
     • Run: opndossier convert -i "$SAMPLE_CONFIG" -o /tmp/report-template.md --use-template
     • Handle errors gracefully (expected if no templates exist)
     • Display success or warning message
   • Generate programmatic mode report:
     • Run: opndossier convert -i "$SAMPLE_CONFIG" -o /tmp/report-programmatic.md
     • Exit with error if programmatic mode fails
     • Display success message
   • Compare outputs if both reports generated:
     • Count lines in each report using wc -l
     • Display line counts and difference
     • Generate detailed diff: diff -u /tmp/report-template.md /tmp/report-programmatic.md > /tmp/migration-diff.txt
     • Suppress diff errors (expected differences)
     • Display diff file location

8. Summary and Next Steps:

   • Display completion message
   • List actionable next steps:
     • Review function mappings in docs/template-function-migration.md
     • Check detailed diff at /tmp/migration-diff.txt
     • Follow migration guide at docs/migration.md

9. Error Handling:

   • Use proper exit codes (0 for success, 1 for errors)
   • Redirect errors to stderr where appropriate
   • Provide helpful error messages with context

10. Cross-Platform Compatibility:

    • Use POSIX-compliant bash syntax
    • Test on Linux, macOS, and Windows (Git Bash)
    • Avoid GNU-specific extensions where possible

The script should be executable (chmod +x) and well-commented for maintainability. Reference the convert command implementation in cmd/convert.go for correct flag usage.

Diagram

sequenceDiagram
    participant User as Custom Template User
    participant Docs as Migration Documentation
    participant Script as validate-migration.sh
    participant CLI as opnDossier CLI
    participant Builder as MarkdownBuilder

    User->>Docs: Read migration.md
    Docs-->>User: Deprecation timeline (v3.0 removal)
    Docs-->>User: Quick start guide
    
    User->>Script: Run validation script
    Script->>Script: Detect custom templates
    Script->>Script: Extract template functions
    Script->>CLI: Generate template report (--use-template)
    CLI-->>Script: Template output
    Script->>CLI: Generate programmatic report
    CLI->>Builder: Use MarkdownBuilder methods
    Builder-->>CLI: Programmatic output
    CLI-->>Script: Programmatic output
    Script->>Script: Compare outputs (diff)
    Script-->>User: Validation results + diff

    User->>Docs: Review function mappings
    Docs-->>User: Template → Go method mappings
    
    User->>User: Implement custom builder
    Note over User: Extend MarkdownBuilder<br/>Port template logic to Go
    
    User->>CLI: Test with programmatic mode
    CLI->>Builder: Execute custom methods
    Builder-->>CLI: Generated report
    CLI-->>User: Validated output
    
    User->>Docs: Review contributing guide
    User->>User: Submit PR (optional)

Loading

Import In IDE

🤖 Prompt for AI Agents

I have created the following plan after thorough exploration and analysis of the codebase. Follow the below plan verbatim. Trust the files and references. Do not re-verify what's written in the plan. Explore only when absolutely necessary. First implement all the proposed file changes and then I'll review all the changes together at the end.

### Observations

The opnDossier project is transitioning from template-based to programmatic markdown generation in v2.0. Existing migration documentation (`docs/migration.md` and `docs/template-function-migration.md`) provides a solid foundation but lacks critical information for custom template users. The codebase has 30+ MarkdownBuilder methods already implemented across `markdown_utils.go`, `markdown_security.go`, `markdown_transformers.go`, and `markdown.go`. The HybridGenerator supports both modes via the `--use-template` flag. No scripts directory exists yet.

### Approach

Enhance existing migration documentation with deprecation timeline, custom template user guidance, real-world examples, and contributing guidelines. Create a migration validator script to help users assess and validate their migration. Update the function mapping table to reflect all currently implemented MarkdownBuilder methods. This documentation-focused approach ensures custom template users have clear, actionable guidance for migrating before v3.0 template removal.

### Reasoning

I explored the repository structure, read existing migration documentation files (`docs/migration.md` and `docs/template-function-migration.md`), examined the MarkdownBuilder implementation across multiple files to identify all available methods, reviewed the HybridGenerator to understand template/programmatic mode switching, and searched for existing scripts (none found). This provided complete context for the documentation enhancement task.

## Mermaid Diagram

sequenceDiagram
    participant User as Custom Template User
    participant Docs as Migration Documentation
    participant Script as validate-migration.sh
    participant CLI as opnDossier CLI
    participant Builder as MarkdownBuilder

    User->>Docs: Read migration.md
    Docs-->>User: Deprecation timeline (v3.0 removal)
    Docs-->>User: Quick start guide
    
    User->>Script: Run validation script
    Script->>Script: Detect custom templates
    Script->>Script: Extract template functions
    Script->>CLI: Generate template report (--use-template)
    CLI-->>Script: Template output
    Script->>CLI: Generate programmatic report
    CLI->>Builder: Use MarkdownBuilder methods
    Builder-->>CLI: Programmatic output
    CLI-->>Script: Programmatic output
    Script->>Script: Compare outputs (diff)
    Script-->>User: Validation results + diff

    User->>Docs: Review function mappings
    Docs-->>User: Template → Go method mappings
    
    User->>User: Implement custom builder
    Note over User: Extend MarkdownBuilder<br/>Port template logic to Go
    
    User->>CLI: Test with programmatic mode
    CLI->>Builder: Execute custom methods
    Builder-->>CLI: Generated report
    CLI-->>User: Validated output
    
    User->>Docs: Review contributing guide
    User->>User: Submit PR (optional)

## Proposed File Changes

### docs/migration.md(MODIFY)

References: 

- docs/template-function-migration.md(MODIFY)
- internal/converter/markdown_utils.go
- internal/converter/markdown_security.go
- internal/converter/markdown_transformers.go
- internal/markdown/hybrid_generator.go

Add four major sections to enhance the existing migration guide:

1. **Deprecation Timeline Section** (insert after "Why Migrate?" section, before "Migration Checklist"):
   - Add clear timeline showing v2.0 (current with `--use-template` flag), v2.1-v2.5 (deprecated with warnings), and v3.0 (complete removal)
   - Include estimated dates (Q2 2025 for v2.5 migration deadline)
   - Emphasize urgency with action required callout

2. **Custom Template User Quick Start Section** (insert after "Migration Checklist", before "Step-by-Step Migration"):
   - Add three-step assessment process: run validator, map functions, choose migration path
   - Include Option A (continue with templates temporarily using `--use-template`) and Option B (migrate to programmatic)
   - Reference the validator script at `scripts/validate-migration.sh`
   - Link to function mapping table in `docs/template-function-migration.md`

3. **Real-World Migration Examples Section** (insert after existing "Example 2: Custom Function Migration", before "Performance Validation"):
   - Add Example 3: Custom Risk Assessment Section showing SecurityBuilder extending MarkdownBuilder
   - Demonstrate usage of inherited methods like `AssessRiskLevel` from `markdown_security.go`
   - Add Example 4: Custom Compliance Report showing compliance checking with firewall rules
   - Include Example 5: Custom Network Analysis showing interface grouping and filtering
   - Each example should show complete struct definition and method implementation patterns
   - Reference actual MarkdownBuilder methods from `internal/converter/markdown_utils.go`, `markdown_security.go`, and `markdown_transformers.go`

4. **Contributing Custom Functions Section** (append at end of document, after "Next Steps"):
   - Add contribution process with four steps: implement as MarkdownBuilder method, add comprehensive tests, document in migration guide, submit PR
   - Include code structure examples showing where to add methods (`internal/converter/markdown_custom.go`) and tests (`internal/converter/markdown_custom_test.go`)
   - Specify PR requirements: clear use case description, before/after examples, test coverage report
   - Reference existing test patterns from `internal/converter/markdown_utils_test.go`

5. **FAQ Section** (insert before "Next Steps" section):
   - Add Q&A covering: template support timeline (v3.0 removal), hybrid mode usage (`--use-template` flag), performance expectations (74% faster, 78% less memory), rollback procedures (use `--use-template` flag)
   - Include troubleshooting for common migration issues
   - Reference HybridGenerator behavior from `internal/markdown/hybrid_generator.go`

Ensure all new sections maintain consistent markdown formatting with existing document style, use proper heading levels, include code blocks with syntax highlighting, and cross-reference other documentation files appropriately.

### docs/template-function-migration.md(MODIFY)

References: 

- internal/converter/markdown_utils.go
- internal/converter/markdown_security.go
- internal/converter/markdown_transformers.go
- internal/converter/markdown.go

Update the function mapping tables to reflect all currently implemented MarkdownBuilder methods:

1. **Update Phase 1: Core Utility Functions table**:
   - Change status of `escapeTableContent` from "Pending" to "**Migrated**" (implemented in `markdown_utils.go` line 13)
   - Change status of `isLast` from "Pending" to "**Migrated**" (implemented as `IsLastInSlice` in `markdown_utils.go` line 79)
   - Change status of `truncateDescription` from "Pending" to "**Migrated**" (implemented in `markdown_utils.go` line 57)

2. **Update Phase 2: Data Transformation Functions table**:
   - Change status of `filterTunables` from "Pending" to "**Migrated**" (implemented as `FilterSystemTunables` in `markdown_transformers.go` line 26)
   - Add note that it includes security prefix filtering logic

3. **Update Phase 3: Security and Compliance Functions table**:
   - Change status of `getRiskLevel` from "Pending" to "**Migrated**" (implemented as `AssessRiskLevel` in `markdown_security.go` line 20)
   - Add new row for `calculateSecurityScore` → `CalculateSecurityScore(data *model.OpnSenseDocument) int` with status "**Migrated**" (implemented in `markdown_security.go` line 42)
   - Add new row for `assessServiceRisk` → `AssessServiceRisk(service model.Service) string` with status "**Migrated**" (implemented in `markdown_security.go` line 91)

4. **Update Phase 4: Sprig Function Replacements (High Priority) table**:
   - Change status of `upper`, `lower`, `trim` from "Pending" to "**Migrated**" (implemented as `ToUpper`, `ToLower`, `TrimSpace` in `markdown_utils.go` lines 130, 135, 140)
   - Change status of `default` from "Pending" to "**Migrated**" (implemented as `DefaultValue` in `markdown_utils.go` line 93)
   - Change status of `empty` from "Pending" to "**Migrated**" (implemented as `IsEmpty` in `markdown_utils.go` line 101)

5. **Add new section: Phase 5: Advanced Data Operations**:
   - Create new table with migrated methods from `markdown_transformers.go`:
     - `GroupServicesByStatus(services []model.Service) map[string][]model.Service` - Status: **Migrated**
     - `AggregatePackageStats(packages []model.Package) map[string]int` - Status: **Migrated**
     - `FilterRulesByType(rules []model.Rule, ruleType string) []model.Rule` - Status: **Migrated**
     - `ExtractUniqueValues(items []string) []string` - Status: **Migrated**

6. **Add new section: Phase 6: Report Building Methods**:
   - Create new table with high-level report building methods from `markdown.go`:
     - `BuildSystemSection(data *model.OpnSenseDocument) string` - Status: **Migrated**
     - `BuildNetworkSection(data *model.OpnSenseDocument) string` - Status: **Migrated**
     - `BuildSecuritySection(data *model.OpnSenseDocument) string` - Status: **Migrated**
     - `BuildServicesSection(data *model.OpnSenseDocument) string` - Status: **Migrated**
     - `BuildStandardReport(data *model.OpnSenseDocument) (string, error)` - Status: **Migrated**
     - `BuildComprehensiveReport(data *model.OpnSenseDocument) (string, error)` - Status: **Migrated**

7. **Update Implementation Priority section**:
   - Move completed Priority 1 functions to a new "Completed" subsection
   - Update Priority 2 and 3 to reflect remaining work
   - Add note that 30+ methods are now available

8. **Update Migration Complexity Assessment section**:
   - Add "Completed" category listing all migrated functions
   - Update complexity estimates for remaining functions

Maintain existing table formatting, add implementation file references in notes column, and ensure all status changes are clearly marked with bold **Migrated** text.

### scripts(NEW)

Create a new directory to house migration and utility scripts for the opnDossier project. This directory will contain the migration validator script and potentially other automation tools in the future.

### scripts/validate-migration.sh(NEW)

References: 

- cmd/convert.go
- docs/migration.md(MODIFY)
- docs/template-function-migration.md(MODIFY)

Create a comprehensive bash script for migration validation with the following structure:

1. **Script Header**:
   - Shebang line: `#!/bin/bash`
   - Script description and version (v2.0)
   - Set strict error handling: `set -e`

2. **Argument Parsing**:
   - Accept two arguments: TEMPLATE_DIR (default: current directory) and SAMPLE_CONFIG (default: sample.xml)
   - Display usage information if --help flag is provided

3. **Banner Display**:
   - Print ASCII art banner: "opnDossier Migration Validation Tool"
   - Include version and purpose information

4. **Prerequisites Check**:
   - Verify `opndossier` command is available in PATH
   - If not found, display installation instructions: `go install github.com/EvilBit-Labs/opnDossier@latest`
   - Exit with error code 1 if prerequisite not met

5. **Custom Template Detection**:
   - Check if `$TEMPLATE_DIR/templates` directory exists
   - If found, display confirmation message with path
   - Extract custom template functions using grep:
     - Search for template function patterns: `{{ *\([a-zA-Z_][a-zA-Z0-9_]*\)`
     - Filter out Go template keywords (if, range, end, define, template, with, block)
     - Sort and display unique function names
   - If no templates found, display informational message

6. **Unmigrated Function Check**:
   - Cross-reference detected functions with known MarkdownBuilder methods
   - Display warning for functions without Go equivalents
   - Reference `docs/template-function-migration.md` for mapping details

7. **Comparison Report Generation** (if sample config provided):
   - Generate template mode report:
     - Run: `opndossier convert -i "$SAMPLE_CONFIG" -o /tmp/report-template.md --use-template`
     - Handle errors gracefully (expected if no templates exist)
     - Display success or warning message
   - Generate programmatic mode report:
     - Run: `opndossier convert -i "$SAMPLE_CONFIG" -o /tmp/report-programmatic.md`
     - Exit with error if programmatic mode fails
     - Display success message
   - Compare outputs if both reports generated:
     - Count lines in each report using `wc -l`
     - Display line counts and difference
     - Generate detailed diff: `diff -u /tmp/report-template.md /tmp/report-programmatic.md > /tmp/migration-diff.txt`
     - Suppress diff errors (expected differences)
     - Display diff file location

8. **Summary and Next Steps**:
   - Display completion message
   - List actionable next steps:
     - Review function mappings in `docs/template-function-migration.md`
     - Check detailed diff at `/tmp/migration-diff.txt`
     - Follow migration guide at `docs/migration.md`

9. **Error Handling**:
   - Use proper exit codes (0 for success, 1 for errors)
   - Redirect errors to stderr where appropriate
   - Provide helpful error messages with context

10. **Cross-Platform Compatibility**:
    - Use POSIX-compliant bash syntax
    - Test on Linux, macOS, and Windows (Git Bash)
    - Avoid GNU-specific extensions where possible

The script should be executable (chmod +x) and well-commented for maintainability. Reference the convert command implementation in `cmd/convert.go` for correct flag usage.

---

Developer Humor

🚀 From templates to types, we migrate with grace,\n> No more runtime errors, compile-time's the place!\n> 74% faster, 78% less RAM,\n> Your custom functions? We've got a plan!\n> 📚 Read the docs, run the script, you're on your way,\n> v3.0's coming, but you'll be ready that day! ✨

---

Execution Information

Branch: main
Commit: 76b9dc7

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.