Swift: support markdown TSP diagnostics

Author: redsun82

swift/integration-tests/linux-only/autobuilder/unsupported-os/diagnostics.expected

@@ -1,15 +1,13 @@
 {
   "helpLinks": [
-    "https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on",
-    "https://docs.github.com/en/enterprise-server/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/customizing-code-scanning",
-    "https://docs.github.com/en/enterprise-server/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-the-codeql-workflow-for-compiled-languages#adding-build-steps-for-a-compiled-language"
+    ""
   ],
-  "plaintextMessage": "CodeQL Swift analysis is currently only officially supported on macOS.\n\nChange the action runner to a macOS one. Analysis on Linux might work, but requires setting up a custom build command.",
+  "markdownMessage": "Currently, `autobuild` for Swift analysis is only supported on macOS.\n\n[Change the Actions runner][1] to run on macOS.\n\nYou may be able to run analysis on Linux by setting up a [manual build command][2].\n\n[1]: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on\n[2]: https://docs.github.com/en/enterprise-server/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-the-codeql-workflow-for-compiled-languages#adding-build-steps-for-a-compiled-language",
   "severity": "error",
   "source": {
     "extractorName": "swift",
     "id": "swift/autobuilder/incompatible-os",
-    "name": "Incompatible operating system for autobuild (expected macOS)"
+    "name": "Incompatible operating system (expected macOS)"
   },
   "visibility": {
     "cliSummaryTable": true,

swift/logging/SwiftDiagnostics.cpp

@@ -25,7 +25,8 @@ nlohmann::json SwiftDiagnostic::json(const std::chrono::system_clock::time_point
        }},
       {"severity", "error"},
       {"helpLinks", std::vector<std::string_view>(absl::StrSplit(helpLinks, ' '))},
-      {"plaintextMessage", absl::StrCat(message, ".\n\n", action, ".")},
+      {format == Format::markdown ? "markdownMessage" : "plaintextMessage",
+       absl::StrCat(message, ".\n\n", action)},
       {"timestamp", fmt::format("{:%FT%T%z}", timestamp)},
   };
   if (location) {

swift/logging/SwiftDiagnostics.h

@@ -33,6 +33,11 @@ struct SwiftDiagnosticsLocation {
 // These are internally stored into a map on id's. A specific error log can use binlog's category
 // as id, which will then be used to recover the diagnostic source while dumping.
 struct SwiftDiagnostic {
+  enum class Format {
+    plaintext,
+    markdown,
+  };
+
   enum class Visibility : unsigned char {
     none = 0b000,
     statusPage = 0b001,
@@ -44,6 +49,7 @@ struct SwiftDiagnostic {
   std::string_view id;
   std::string_view name;
   static constexpr std::string_view extractorName = "swift";
+  Format format;
   std::string_view action;
   // space separated if more than 1. Not a vector to allow constexpr
   // TODO(C++20) with vector going constexpr this can be turned to `std::vector<std::string_view>`
@@ -54,15 +60,20 @@ struct SwiftDiagnostic {
 
   std::optional<SwiftDiagnosticsLocation> location{};
 
+  // notice help links are really required only for plaintext messages, otherwise they should be
+  // directly embedded in the markdown message
   constexpr SwiftDiagnostic(std::string_view id,
                             std::string_view name,
+                            Format format,
                             std::string_view action = "",
                             std::string_view helpLinks = "",
                             Visibility visibility = Visibility::all)
-      : id{id}, name{name}, action{action}, helpLinks{helpLinks}, visibility{visibility} {}
-
-  constexpr SwiftDiagnostic(std::string_view id, std::string_view name, Visibility visibility)
-      : SwiftDiagnostic(id, name, "", "", visibility) {}
+      : id{id},
+        name{name},
+        format{format},
+        action{action},
+        helpLinks{helpLinks},
+        visibility{visibility} {}
 
   // create a JSON diagnostics for this source with the given timestamp and message to out
   // A plaintextMessage is used that includes both the message and the action to take. Dots are
@@ -103,6 +114,9 @@ inline constexpr SwiftDiagnostic::Visibility operator&(SwiftDiagnostic::Visibili
 constexpr SwiftDiagnostic internalError{
     "internal-error",
     "Internal error",
+    SwiftDiagnostic::Format::plaintext,
+    /* action=*/"",
+    /* helpLinks=*/"",
     SwiftDiagnostic::Visibility::telemetry,
 };
 }  // namespace codeql

swift/tools/autobuilder-diagnostics/IncompatibleOs.cpp

@@ -9,13 +9,16 @@
 const std::string_view codeql::programName = "autobuilder";
 
 constexpr codeql::SwiftDiagnostic incompatibleOs{
-    "incompatible-os", "Incompatible operating system for autobuild (expected macOS)",
-    "Change the action runner to a macOS one. Analysis on Linux might work, but requires setting "
-    "up a custom build command",
+    "incompatible-os", "Incompatible operating system (expected macOS)",
+    codeql::SwiftDiagnostic::Format::markdown,
+    "[Change the Actions runner][1] to run on macOS.\n"
+    "\n"
+    "You may be able to run analysis on Linux by setting up a [manual build command][2].\n"
+    "\n"
+    "[1]: "
     "https://docs.github.com/en/actions/using-workflows/"
-    "workflow-syntax-for-github-actions#jobsjob_idruns-on "
-    "https://docs.github.com/en/enterprise-server/code-security/code-scanning/"
-    "automatically-scanning-your-code-for-vulnerabilities-and-errors/customizing-code-scanning "
+    "workflow-syntax-for-github-actions#jobsjob_idruns-on\n"
+    "[2]: "
     "https://docs.github.com/en/enterprise-server/code-security/code-scanning/"
     "automatically-scanning-your-code-for-vulnerabilities-and-errors/"
     "configuring-the-codeql-workflow-for-compiled-languages#adding-build-steps-for-a-compiled-"
@@ -28,6 +31,6 @@ static codeql::Logger& logger() {
 
 int main() {
   DIAGNOSE_ERROR(incompatibleOs,
-                 "CodeQL Swift analysis is currently only officially supported on macOS");
+                 "Currently, `autobuild` for Swift analysis is only supported on macOS");
   return 1;
 }

swift/xcode-autobuilder/CustomizingBuildDiagnostics.h

@@ -1,7 +1,7 @@
 #include <string_view>
 
 namespace codeql {
-constexpr std::string_view customizingBuildAction = "Set up a manual build command";
+constexpr std::string_view customizingBuildAction = "Set up a manual build command.";
 constexpr std::string_view customizingBuildHelpLinks =
     "https://docs.github.com/en/enterprise-server/code-security/code-scanning/"
     "automatically-scanning-your-code-for-vulnerabilities-and-errors/customizing-code-scanning "

swift/xcode-autobuilder/XcodeBuildRunner.cpp

@@ -9,7 +9,8 @@
 #include "swift/xcode-autobuilder/CustomizingBuildDiagnostics.h"
 
 constexpr codeql::SwiftDiagnostic buildCommandFailed{
-    "build-command-failed", "Detected build command failed", codeql::customizingBuildAction,
+    "build-command-failed", "Detected build command failed",
+    codeql::SwiftDiagnostic::Format::plaintext, codeql::customizingBuildAction,
     codeql::customizingBuildHelpLinks};
 
 static codeql::Logger& logger() {

swift/xcode-autobuilder/xcode-autobuilder.cpp

@@ -13,16 +13,19 @@ static const char* unitTest = "com.apple.product-type.bundle.unit-test";
 const std::string_view codeql::programName = "autobuilder";
 
 constexpr codeql::SwiftDiagnostic noProjectFound{
-    "no-project-found", "No Xcode project or workspace detected", codeql::customizingBuildAction,
+    "no-project-found", "No Xcode project or workspace detected",
+    codeql::SwiftDiagnostic::Format::plaintext, codeql::customizingBuildAction,
     codeql::customizingBuildHelpLinks};
 
 constexpr codeql::SwiftDiagnostic noSwiftTarget{
-    "no-swift-target", "No Swift compilation target found", codeql::customizingBuildAction,
+    "no-swift-target", "No Swift compilation target found",
+    codeql::SwiftDiagnostic::Format::plaintext, codeql::customizingBuildAction,
     codeql::customizingBuildHelpLinks};
 
 constexpr codeql::SwiftDiagnostic spmNotSupported{
     "spm-not-supported", "Swift Package Manager build unsupported by autobuild",
-    codeql::customizingBuildAction, codeql::customizingBuildHelpLinks};
+    codeql::SwiftDiagnostic::Format::plaintext, codeql::customizingBuildAction,
+    codeql::customizingBuildHelpLinks};
 
 static codeql::Logger& logger() {
   static codeql::Logger ret{"main"};