| | 1 | | // Copyright DotNet API Diff Project Contributors - SPDX Identifier: MIT |
| | 2 | | using DotNetApiDiff.Interfaces; |
| | 3 | | using DotNetApiDiff.Models; |
| | 4 | | using System.Text; |
| | 5 | |
|
| | 6 | | namespace DotNetApiDiff.Reporting; |
| | 7 | |
|
| | 8 | | /// <summary> |
| | 9 | | /// Formatter for Markdown output with human-readable documentation |
| | 10 | | /// </summary> |
| | 11 | | public class MarkdownFormatter : IReportFormatter |
| | 12 | | { |
| | 13 | | /// <summary> |
| | 14 | | /// Formats a comparison result as Markdown |
| | 15 | | /// </summary> |
| | 16 | | /// <param name="result">The comparison result to format</param> |
| | 17 | | /// <returns>Formatted Markdown output as a string</returns> |
| | 18 | | public string Format(ComparisonResult result) |
| 5 | 19 | | { |
| 5 | 20 | | var output = new StringBuilder(); |
| | 21 | |
|
| | 22 | | // Create header with title and assembly information |
| 5 | 23 | | output.AppendLine("# API Comparison Report"); |
| 5 | 24 | | output.AppendLine(); |
| | 25 | |
|
| | 26 | | // Add metadata section |
| 5 | 27 | | output.AppendLine("## Metadata"); |
| 5 | 28 | | output.AppendLine(); |
| 5 | 29 | | output.AppendLine("| Property | Value |"); |
| 5 | 30 | | output.AppendLine("|----------|-------|"); |
| 5 | 31 | | output.AppendLine($"| Source Assembly | `{Path.GetFileName(result.OldAssemblyPath)}` |"); |
| 5 | 32 | | output.AppendLine($"| Target Assembly | `{Path.GetFileName(result.NewAssemblyPath)}` |"); |
| 5 | 33 | | output.AppendLine($"| Comparison Date | {result.ComparisonTimestamp:yyyy-MM-dd HH:mm:ss} |"); |
| 5 | 34 | | output.AppendLine($"| Total Differences | {result.TotalDifferences} |"); |
| | 35 | |
|
| 5 | 36 | | if (result.HasBreakingChanges) |
| 2 | 37 | | { |
| 7 | 38 | | output.AppendLine($"| Breaking Changes | **{result.Differences.Count(d => d.IsBreakingChange)}** |"); |
| 2 | 39 | | } |
| | 40 | |
|
| 5 | 41 | | output.AppendLine(); |
| | 42 | |
|
| | 43 | | // Add summary section |
| 5 | 44 | | output.AppendLine("## Summary"); |
| 5 | 45 | | output.AppendLine(); |
| 5 | 46 | | output.AppendLine("| Change Type | Count |"); |
| 5 | 47 | | output.AppendLine("|-------------|-------|"); |
| 5 | 48 | | output.AppendLine($"| Added | {result.Summary.AddedCount} |"); |
| 5 | 49 | | output.AppendLine($"| Removed | {result.Summary.RemovedCount} |"); |
| 5 | 50 | | output.AppendLine($"| Modified | {result.Summary.ModifiedCount} |"); |
| 5 | 51 | | output.AppendLine($"| Breaking Changes | {result.Summary.BreakingChangesCount} |"); |
| 5 | 52 | | output.AppendLine($"| **Total Changes** | **{result.Summary.TotalChanges}** |"); |
| 5 | 53 | | output.AppendLine(); |
| | 54 | |
|
| | 55 | | // Add breaking changes section if any exist |
| 5 | 56 | | if (result.HasBreakingChanges) |
| 2 | 57 | | { |
| 2 | 58 | | output.AppendLine("## Breaking Changes"); |
| 2 | 59 | | output.AppendLine(); |
| 2 | 60 | | output.AppendLine("The following changes may break compatibility with existing code:"); |
| 2 | 61 | | output.AppendLine(); |
| | 62 | |
|
| 2 | 63 | | output.AppendLine("| Type | Element | Description | Severity |"); |
| 2 | 64 | | output.AppendLine("|------|---------|-------------|----------|"); |
| | 65 | |
|
| 26 | 66 | | foreach (var change in result.Differences.Where(d => d.IsBreakingChange).OrderBy(d => d.Severity).ThenBy(d = |
| 3 | 67 | | { |
| 3 | 68 | | string severityText = change.Severity switch |
| 3 | 69 | | { |
| 0 | 70 | | SeverityLevel.Critical => $"**{change.Severity}**", |
| 2 | 71 | | SeverityLevel.Error => change.Severity.ToString(), |
| 1 | 72 | | SeverityLevel.Warning => change.Severity.ToString(), |
| 0 | 73 | | _ => change.Severity.ToString() |
| 3 | 74 | | }; |
| | 75 | |
|
| 3 | 76 | | output.AppendLine($"| {change.ElementType} | `{change.ElementName}` | {change.Description} | {severityTe |
| 3 | 77 | | } |
| | 78 | |
|
| 2 | 79 | | output.AppendLine(); |
| 2 | 80 | | } |
| | 81 | |
|
| | 82 | | // Group differences by change type |
| 13 | 83 | | var addedItems = result.Differences.Where(d => d.ChangeType == ChangeType.Added).ToList(); |
| 13 | 84 | | var removedItems = result.Differences.Where(d => d.ChangeType == ChangeType.Removed).ToList(); |
| 13 | 85 | | var modifiedItems = result.Differences.Where(d => d.ChangeType == ChangeType.Modified).ToList(); |
| 13 | 86 | | var excludedItems = result.Differences.Where(d => d.ChangeType == ChangeType.Excluded).ToList(); |
| 13 | 87 | | var movedItems = result.Differences.Where(d => d.ChangeType == ChangeType.Moved).ToList(); |
| | 88 | |
|
| | 89 | | // Add detailed sections for each change type |
| 5 | 90 | | if (addedItems.Any()) |
| 2 | 91 | | { |
| 2 | 92 | | output.AppendLine($"## Added Items ({addedItems.Count})"); |
| 2 | 93 | | output.AppendLine(); |
| 2 | 94 | | FormatChangeGroup(output, addedItems); |
| 2 | 95 | | } |
| | 96 | |
|
| 5 | 97 | | if (removedItems.Any()) |
| 2 | 98 | | { |
| 2 | 99 | | output.AppendLine($"## Removed Items ({removedItems.Count})"); |
| 2 | 100 | | output.AppendLine(); |
| 2 | 101 | | FormatChangeGroup(output, removedItems); |
| 2 | 102 | | } |
| | 103 | |
|
| 5 | 104 | | if (modifiedItems.Any()) |
| 1 | 105 | | { |
| 1 | 106 | | output.AppendLine($"## Modified Items ({modifiedItems.Count})"); |
| 1 | 107 | | output.AppendLine(); |
| 1 | 108 | | FormatChangeGroup(output, modifiedItems); |
| 1 | 109 | | } |
| | 110 | |
|
| 5 | 111 | | if (movedItems.Any()) |
| 0 | 112 | | { |
| 0 | 113 | | output.AppendLine($"## Moved Items ({movedItems.Count})"); |
| 0 | 114 | | output.AppendLine(); |
| 0 | 115 | | FormatChangeGroup(output, movedItems); |
| 0 | 116 | | } |
| | 117 | |
|
| | 118 | | // Add excluded items section if any exist (requirement 7.2) |
| 5 | 119 | | if (excludedItems.Any()) |
| 2 | 120 | | { |
| 2 | 121 | | output.AppendLine($"## Excluded/Unsupported Items ({excludedItems.Count})"); |
| 2 | 122 | | output.AppendLine(); |
| 2 | 123 | | output.AppendLine("The following items were intentionally excluded from the comparison:"); |
| 2 | 124 | | output.AppendLine(); |
| 2 | 125 | | FormatChangeGroup(output, excludedItems); |
| 2 | 126 | | } |
| | 127 | |
|
| 5 | 128 | | return output.ToString(); |
| 5 | 129 | | } |
| | 130 | |
|
| | 131 | | private void FormatChangeGroup(StringBuilder output, List<ApiDifference> changes) |
| 7 | 132 | | { |
| | 133 | | // Group changes by element type for better organization |
| 23 | 134 | | var groupedChanges = changes.GroupBy(c => c.ElementType).OrderBy(g => g.Key); |
| | 135 | |
|
| 37 | 136 | | foreach (var group in groupedChanges) |
| 8 | 137 | | { |
| 8 | 138 | | output.AppendLine($"### {group.Key}"); |
| 8 | 139 | | output.AppendLine(); |
| | 140 | |
|
| 8 | 141 | | output.AppendLine("| Element | Description | Breaking |"); |
| 8 | 142 | | output.AppendLine("|---------|-------------|----------|"); |
| | 143 | |
|
| 48 | 144 | | foreach (var change in group.OrderBy(c => c.ElementName)) |
| 8 | 145 | | { |
| 8 | 146 | | string breakingText = change.IsBreakingChange ? "Yes" : "No"; |
| 8 | 147 | | output.AppendLine($"| `{change.ElementName}` | {change.Description} | {breakingText} |"); |
| | 148 | |
|
| | 149 | | // Add signature details if available |
| 8 | 150 | | if (!string.IsNullOrEmpty(change.OldSignature) || !string.IsNullOrEmpty(change.NewSignature)) |
| 5 | 151 | | { |
| 5 | 152 | | output.AppendLine(); |
| 5 | 153 | | output.AppendLine("<details>"); |
| 5 | 154 | | output.AppendLine("<summary>Signature Details</summary>"); |
| 5 | 155 | | output.AppendLine(); |
| | 156 | |
|
| 5 | 157 | | if (!string.IsNullOrEmpty(change.OldSignature)) |
| 3 | 158 | | { |
| 3 | 159 | | output.AppendLine("**Old:**"); |
| 3 | 160 | | output.AppendLine("```csharp"); |
| 3 | 161 | | output.AppendLine(change.OldSignature); |
| 3 | 162 | | output.AppendLine("```"); |
| 3 | 163 | | } |
| | 164 | |
|
| 5 | 165 | | if (!string.IsNullOrEmpty(change.NewSignature)) |
| 3 | 166 | | { |
| 3 | 167 | | output.AppendLine("**New:**"); |
| 3 | 168 | | output.AppendLine("```csharp"); |
| 3 | 169 | | output.AppendLine(change.NewSignature); |
| 3 | 170 | | output.AppendLine("```"); |
| 3 | 171 | | } |
| | 172 | |
|
| 5 | 173 | | output.AppendLine("</details>"); |
| 5 | 174 | | } |
| 8 | 175 | | } |
| | 176 | |
|
| 8 | 177 | | output.AppendLine(); |
| 8 | 178 | | } |
| 7 | 179 | | } |
| | 180 | | } |