Merge pull request github#13186 from github/redsun82/swift-diagnostics-wording

sashabu · web-flow · commit a1beaa6300ce · 2023-05-19T15:15:46.000+01:00
Swift: reword TSP diagnostics after doc team review
diff --git a/swift/integration-tests/osx-only/autobuilder/failure/diagnostics.expected b/swift/integration-tests/osx-only/autobuilder/failure/diagnostics.expected
@@ -1,9 +1,8 @@
 {
   "helpLinks": [
-    "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": "The detected build command failed (tried /usr/bin/xcodebuild build -project <test-root-directory>/hello-failure.xcodeproj -target hello-failure CODE_SIGNING_REQUIRED=NO CODE_SIGNING_ALLOWED=NO).\n\nSet up a manual build command.",
+  "markdownMessage": "`autobuild` failed to run the detected build command:\n\n```\n/usr/bin/xcodebuild build -project <test-root-directory>/hello-failure.xcodeproj -target hello-failure CODE_SIGNING_REQUIRED=NO CODE_SIGNING_ALLOWED=NO\n```\n\nSet up a [manual build command][1] or [check the logs of the autobuild step][2].\n\n[1]: 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\n[2]: https://docs.github.com/en/actions/monitoring-and-troubleshooting-workflows/using-workflow-run-logs",
   "severity": "error",
   "source": {
     "extractorName": "swift",
diff --git a/swift/integration-tests/osx-only/autobuilder/no-build-system/diagnostics.expected b/swift/integration-tests/osx-only/autobuilder/no-build-system/diagnostics.expected
@@ -1,14 +1,13 @@
 {
   "helpLinks": [
-    "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": "No Xcode project or workspace was found.\n\nSet up a manual build command.",
+  "markdownMessage": "`autobuild` could not detect an Xcode project or workspace.\n\nSet up a [manual build command][1].\n\n[1]: 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/no-project-found",
-    "name": "No Xcode project or workspace detected"
+    "name": "No Xcode project or workspace found"
   },
   "visibility": {
     "cliSummaryTable": true,
diff --git a/swift/integration-tests/osx-only/autobuilder/no-swift-with-spm/diagnostics.expected b/swift/integration-tests/osx-only/autobuilder/no-swift-with-spm/diagnostics.expected
@@ -1,14 +1,13 @@
 {
   "helpLinks": [
-    "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": "No viable Swift Xcode target was found but a Swift package was detected. Swift Package Manager builds are not yet supported by the autobuilder.\n\nSet up a manual build command.",
+  "markdownMessage": "A Swift package was detected, but no viable Xcode target was found.\n\nSwift Package Manager builds are not currently supported by `autobuild`. Set up a [manual build command][1].\n\n[1]: 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/spm-not-supported",
-    "name": "Swift Package Manager build unsupported by autobuild"
+    "name": "Swift Package Manager is not supported"
   },
   "visibility": {
     "cliSummaryTable": true,
diff --git a/swift/integration-tests/osx-only/autobuilder/no-swift/diagnostics.expected b/swift/integration-tests/osx-only/autobuilder/no-swift/diagnostics.expected
@@ -1,9 +1,8 @@
 {
   "helpLinks": [
-    "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": "All targets found within Xcode projects or workspaces either have no Swift sources or are tests.\n\nSet up a manual build command.",
+  "markdownMessage": "All targets found within Xcode projects or workspaces either contain no Swift source files, or are tests.\n\nTo analyze a custom set of source files, set up a [manual build command][1].\n\n[1]: 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",
diff --git a/swift/integration-tests/osx-only/autobuilder/no-xcode-with-spm/diagnostics.expected b/swift/integration-tests/osx-only/autobuilder/no-xcode-with-spm/diagnostics.expected
@@ -1,14 +1,13 @@
 {
   "helpLinks": [
-    "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": "No viable Swift Xcode target was found but a Swift package was detected. Swift Package Manager builds are not yet supported by the autobuilder.\n\nSet up a manual build command.",
+  "markdownMessage": "A Swift package was detected, but no viable Xcode target was found.\n\nSwift Package Manager builds are not currently supported by `autobuild`. Set up a [manual build command][1].\n\n[1]: 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/spm-not-supported",
-    "name": "Swift Package Manager build unsupported by autobuild"
+    "name": "Swift Package Manager is not supported"
   },
   "visibility": {
     "cliSummaryTable": true,
diff --git a/swift/integration-tests/osx-only/autobuilder/only-tests-with-spm/diagnostics.expected b/swift/integration-tests/osx-only/autobuilder/only-tests-with-spm/diagnostics.expected
@@ -1,14 +1,13 @@
 {
   "helpLinks": [
-    "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": "No viable Swift Xcode target was found but a Swift package was detected. Swift Package Manager builds are not yet supported by the autobuilder.\n\nSet up a manual build command.",
+  "markdownMessage": "A Swift package was detected, but no viable Xcode target was found.\n\nSwift Package Manager builds are not currently supported by `autobuild`. Set up a [manual build command][1].\n\n[1]: 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/spm-not-supported",
-    "name": "Swift Package Manager build unsupported by autobuild"
+    "name": "Swift Package Manager is not supported"
   },
   "visibility": {
     "cliSummaryTable": true,
diff --git a/swift/integration-tests/osx-only/autobuilder/only-tests/diagnostics.expected b/swift/integration-tests/osx-only/autobuilder/only-tests/diagnostics.expected
@@ -1,9 +1,8 @@
 {
   "helpLinks": [
-    "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": "All targets found within Xcode projects or workspaces either have no Swift sources or are tests.\n\nSet up a manual build command.",
+  "markdownMessage": "All targets found within Xcode projects or workspaces either contain no Swift source files, or are tests.\n\nTo analyze a custom set of source files, set up a [manual build command][1].\n\n[1]: 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",
diff --git a/swift/logging/SwiftDiagnostics.cpp b/swift/logging/SwiftDiagnostics.cpp
@@ -42,7 +42,7 @@ nlohmann::json SwiftDiagnostic::json(const std::chrono::system_clock::time_point
       {"severity", severityToString(severity)},
       {"helpLinks", std::vector<std::string_view>(absl::StrSplit(helpLinks, ' '))},
       {format == Format::markdown ? "markdownMessage" : "plaintextMessage",
-       absl::StrCat(message, ".\n\n", action)},
+       absl::StrCat(message, "\n\n", action)},
       {"timestamp", fmt::format("{:%FT%T%z}", timestamp)},
   };
   if (location) {
diff --git a/swift/logging/SwiftDiagnostics.h b/swift/logging/SwiftDiagnostics.h
@@ -93,8 +93,8 @@ struct SwiftDiagnostic {
 
   // create a JSON diagnostics for this source with the given `timestamp` and `message`
   // Depending on format, either a plaintextMessage or markdownMessage is used that includes both
-  // the message and the action to take. A dot '.' is appended to `message`. The id is used to
-  // construct the source id in the form `swift/<prog name>/<id>`
+  // the message and the action to take. The id is used to construct the source id in the form
+  // `swift/<prog name>/<id>`
   nlohmann::json json(const std::chrono::system_clock::time_point& timestamp,
                       std::string_view message) const;
 
diff --git a/swift/logging/tests/assertion-diagnostics/AssertFalse.cpp b/swift/logging/tests/assertion-diagnostics/AssertFalse.cpp
@@ -8,5 +8,6 @@ static codeql::Logger& logger() {
 }
 
 int main() {
-  CODEQL_ASSERT(false, "Format the int {} and string {} if this assertion fails", 1234, "myString");
+  CODEQL_ASSERT(false, "Format the int {} and string {} if this assertion fails.", 1234,
+                "myString");
 }
diff --git a/swift/tools/autobuilder-diagnostics/IncompatibleOs.cpp b/swift/tools/autobuilder-diagnostics/IncompatibleOs.cpp
@@ -32,6 +32,6 @@ static codeql::Logger& logger() {
 
 int main() {
   DIAGNOSE_ERROR(incompatibleOs,
-                 "Currently, `autobuild` for Swift analysis is only supported on macOS");
+                 "Currently, `autobuild` for Swift analysis is only supported on macOS.");
   return 1;
 }
diff --git a/swift/xcode-autobuilder/CustomizingBuildDiagnostics.h b/swift/xcode-autobuilder/CustomizingBuildDiagnostics.h
diff --git a/swift/xcode-autobuilder/CustomizingBuildLink.h b/swift/xcode-autobuilder/CustomizingBuildLink.h
@@ -0,0 +1,12 @@
+#include <string_view>
+#include "swift/logging/SwiftDiagnostics.h"
+
+#define MANUAL_BUILD_COMMAND_HELP_LINK                                                        \
+  "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"
+
+#define CHECK_LOGS_HELP_LINK                                                     \
+  "https://docs.github.com/en/actions/monitoring-and-troubleshooting-workflows/" \
+  "using-workflow-run-logs"
diff --git a/swift/xcode-autobuilder/XcodeBuildRunner.cpp b/swift/xcode-autobuilder/XcodeBuildRunner.cpp
@@ -6,11 +6,12 @@
 #include "absl/strings/str_join.h"
 
 #include "swift/logging/SwiftLogging.h"
-#include "swift/xcode-autobuilder/CustomizingBuildDiagnostics.h"
+#include "swift/xcode-autobuilder/CustomizingBuildLink.h"
 
 constexpr codeql::SwiftDiagnostic buildCommandFailed{
-    "build-command-failed", "Detected build command failed", codeql::customizingBuildAction,
-    codeql::SwiftDiagnostic::Format::plaintext, codeql::customizingBuildHelpLinks};
+    "build-command-failed", "Detected build command failed",
+    "Set up a [manual build command][1] or [check the logs of the autobuild step][2].\n"
+    "\n[1]: " MANUAL_BUILD_COMMAND_HELP_LINK "\n[2]: " CHECK_LOGS_HELP_LINK};
 
 static codeql::Logger& logger() {
   static codeql::Logger ret{"build"};
@@ -68,7 +69,8 @@ void buildTarget(Target& target, bool dryRun) {
     std::cout << absl::StrJoin(argv, " ") << "\n";
   } else {
     if (!exec(argv)) {
-      DIAGNOSE_ERROR(buildCommandFailed, "The detected build command failed (tried {})",
+      DIAGNOSE_ERROR(buildCommandFailed,
+                     "`autobuild` failed to run the detected build command:\n\n```\n{}\n```",
                      absl::StrJoin(argv, " "));
       codeql::Log::flush();
       exit(1);
diff --git a/swift/xcode-autobuilder/xcode-autobuilder.cpp b/swift/xcode-autobuilder/xcode-autobuilder.cpp
@@ -5,25 +5,28 @@
 #include "swift/xcode-autobuilder/XcodeBuildRunner.h"
 #include "swift/xcode-autobuilder/XcodeProjectParser.h"
 #include "swift/logging/SwiftLogging.h"
-#include "swift/xcode-autobuilder/CustomizingBuildDiagnostics.h"
+#include "swift/xcode-autobuilder/CustomizingBuildLink.h"
 
 static const char* uiTest = "com.apple.product-type.bundle.ui-testing";
 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,
-    codeql::SwiftDiagnostic::Format::plaintext, codeql::customizingBuildHelpLinks};
+constexpr codeql::SwiftDiagnostic noProjectFound{"no-project-found",
+                                                 "No Xcode project or workspace found",
+                                                 "Set up a [manual build command][1].\n"
+                                                 "\n[1]: " MANUAL_BUILD_COMMAND_HELP_LINK};
 
 constexpr codeql::SwiftDiagnostic noSwiftTarget{
-    "no-swift-target", "No Swift compilation target found", codeql::customizingBuildAction,
-    codeql::SwiftDiagnostic::Format::plaintext, codeql::customizingBuildHelpLinks};
+    "no-swift-target", "No Swift compilation target found",
+    "To analyze a custom set of source files, set up a [manual build command][1].\n"
+    "\n[1]: " MANUAL_BUILD_COMMAND_HELP_LINK};
 
 constexpr codeql::SwiftDiagnostic spmNotSupported{
-    "spm-not-supported", "Swift Package Manager build unsupported by autobuild",
-    codeql::customizingBuildAction, codeql::SwiftDiagnostic::Format::plaintext,
-    codeql::customizingBuildHelpLinks};
+    "spm-not-supported", "Swift Package Manager is not supported",
+    "Swift Package Manager builds are not currently supported by `autobuild`. Set up a [manual "
+    "build command][1].\n"
+    "\n[1]: " MANUAL_BUILD_COMMAND_HELP_LINK};
 
 static codeql::Logger& logger() {
   static codeql::Logger ret{"main"};
@@ -53,13 +56,12 @@ static void autobuild(const CLIArgs& args) {
             [](Target& lhs, Target& rhs) { return lhs.fileCount > rhs.fileCount; });
   if ((!collected.xcodeEncountered || targets.empty()) && collected.swiftPackageEncountered) {
     DIAGNOSE_ERROR(spmNotSupported,
-                   "No viable Swift Xcode target was found but a Swift package was detected. Swift "
-                   "Package Manager builds are not yet supported by the autobuilder");
+                   "A Swift package was detected, but no viable Xcode target was found.");
   } else if (!collected.xcodeEncountered) {
-    DIAGNOSE_ERROR(noProjectFound, "No Xcode project or workspace was found");
+    DIAGNOSE_ERROR(noProjectFound, "`autobuild` could not detect an Xcode project or workspace.");
   } else if (targets.empty()) {
     DIAGNOSE_ERROR(noSwiftTarget, "All targets found within Xcode projects or workspaces either "
-                                  "have no Swift sources or are tests");
+                                  "contain no Swift source files, or are tests.");
   } else {
     LOG_INFO("Selected {}", targets.front());
     buildTarget(targets.front(), args.dryRun);

Original file line number	Diff line number	Diff line change
`@@ -8,5 +8,6 @@ static codeql::Logger& logger() {`
`8`	`8`	`}`
`9`	`9`
`10`	`10`	`int main() {`
`11`		`- CODEQL_ASSERT(false, "Format the int {} and string {} if this assertion fails", 1234, "myString");`
	`11`	`+ CODEQL_ASSERT(false, "Format the int {} and string {} if this assertion fails.", 1234,`
	`12`	`+ "myString");`
`12`	`13`	`}`