[apidiff] Compare Xamarin.iOS between iOS and MacCatalyst (#10924)

Xamarin.MacCatalyst ships a `Xamarin.iOS.dll` assembly that contains
forwarders (to `Xamarin.MacCatalyst.dll`) and stubs that throws
`PlatformNotSupportedException`.

This is used to help code compatibility between both platforms - but
that requires exposing an identical surface and the best way to ensure
this is to compare (and report) them using `apidiff`

Co-authored-by: Manuel de la Pena <mandel@microsoft.com>

tools/apidiff/Makefile

@@ -97,6 +97,11 @@ $(APIDIFF_DIR)/diff/ios-to-tvos.html: $(APIDIFF_DIR)/temp/xi/Xamarin.iOS/Xamarin
 	$(Q) sed -e 's_<assembly name="Xamarin.TVOS" version="0.0.0.0">_<assembly name="Xamarin.iOS" version="0.0.0.0">_' $(APIDIFF_DIR)/temp/xi/Xamarin.TVOS/Xamarin.TVOS.xml > $(APIDIFF_DIR)/temp/Xamarin.TVOS-as-iOS.xml
 	$(QF_GEN) $(MONO_BUILD) --debug $(MONO_API_HTML) $< $(APIDIFF_DIR)/temp/Xamarin.TVOS-as-iOS.xml $@
 
+# this is a hack to show the difference between Catalyst (iOS) and iOS
+$(APIDIFF_DIR)/maccat-to-ios.md: $(APIDIFF_DIR)/temp/xi/Xamarin.iOS/Xamarin.iOS.xml $(APIDIFF_DIR)/temp/xi/Xamarin.MacCatalyst/Xamarin.iOS.xml
+	$(Q) mkdir -p $(dir $@)
+	$(QF_GEN) $(MONO_BUILD) --debug $(MONO_API_HTML) --md $^ $@
+
 # create diff files for all the assemblies per platform
 
 $(APIDIFF_DIR)/mac-api-diff.html:     $(foreach file,$(MAC_ASSEMBLIES),$(APIDIFF_DIR)/diff/xm/$(file).html)
@@ -139,6 +144,7 @@ API_DIFF_DEPENDENCIES += $(APIDIFF_DIR)/diff/ios-to-tvos.html
 endif
 ifdef INCLUDE_MACCATALYST
 API_DIFF_DEPENDENCIES += $(APIDIFF_DIR)/maccat-api-diff.html
+API_DIFF_DEPENDENCIES += $(APIDIFF_DIR)/maccat-to-ios.md
 endif
 endif
 
@@ -325,6 +331,7 @@ ifdef INCLUDE_TVOS
 endif
 ifdef INCLUDE_MACCATALYST
 	@echo "@MonkeyWrench: AddFile: $(CURDIR)/maccat-api-diff.html"
+	@echo "@MonkeyWrench: AddFile: $(CURDIR)/maccat-to-ios.md"
 endif
 endif
 	$(Q) $(MAKE) $(UNZIP_STAMP)

tools/devops/automation/scripts/GitHub.psm1

@@ -446,7 +446,7 @@ function New-GitHubSummaryComment {
             # we are dealing with an object, not a dictionary
             $hasHtmlLinks = "html" -in $json.PSobject.Properties.Name
             $hasMDlinks = "gist" -in $json.PSobject.Properties.Name
-            if ($hasHtmlLinks -and $hasMDlinks) {
+            if ($hasHtmlLinks -or $hasMDlinks) {
                 # build the required list
                 $sb.AppendLine("# API diff")
                 Write-Host "Message is '$($json.message)'"
@@ -454,10 +454,33 @@ function New-GitHubSummaryComment {
                 $sb.AppendLine("<details><summary>View API diff</summary>")
                 $sb.AppendLine("") # no new line results in a bad rendering in the links
 
-                foreach ($linkPlatform in @("iOS", "macOS", "macCat", "tvOS", "watchOS")) {
-                    $htmlLink = $json.html | Select-Object -ExpandProperty $linkPlatform 
-                    $gistLink = $json.gist | Select-Object -ExpandProperty $linkPlatform 
-                    $sb.AppendLine("* $linkPlatform [vsdrops]($htmlLink) [gist]($gistLink)")
+                foreach ($linkPlatform in @("iOS", "macOS", "macCat", "macCatiOS", "tvOS", "watchOS")) {
+                    $htmlLink = ""
+                    $gistLink = ""
+
+                    $platformHasHtmlLinks = $linkPlatform -in $json.html.PSobject.Properties.Name
+                    $platformHasMDlinks = $linkPlatform -in $json.gist.PSobject.Properties.Name
+                    
+                    # some do not have md, some do not have html
+                    if ($platformHasHtmlLinks) {
+                        Write-Host "Found html link for $linkPlatform"
+                        $htmlLinkUrl = $json.html | Select-Object -ExpandProperty $linkPlatform 
+                        $htmlLink = "[vsdrops]($htmlLinkUrl)"
+                    }
+
+                    if ($platformHasMDlinks) {
+                        Write-Host "Found gist link for $linkPlatform"
+                        $gistLinkUrl = $json.gist | Select-Object -ExpandProperty $linkPlatform 
+                        $gistLink = "[gist]($gistLinkUrl)"
+                    }
+
+                    if (($htmlLink -eq "") -and ($gistLink -eq "")) {
+                        $sb.AppendLine("* :fire: $linkPlatform :fire: Missing files")
+                    } else {
+                        # I don't like extra ' ' when we are missing vars, use join
+                        $line = @("*", $linkPlatform, $htmlLink, $gistLink) -join " "
+                        $sb.AppendLine($line)
+                    }
                 }
 
                 $sb.AppendLine("</details>")

tools/devops/automation/templates/build/publish-html.yml

@@ -39,7 +39,8 @@ steps:
     $filePatterns = @{
       "iOS" = "ios-*.md";
       "macOS" = "macos-*.md";
-      "macCat" = "maccat-*.md";
+      "macCat" = "maccat-api*.md";
+      "macCatiOS" = "maccat-to-ios*.md";
       "tvOS" = "tvos-*.md";
       "watchOS" = "watchos-*.md";
     }