Add an attribute that emits a warning. (#895)

This PR adds an attribute (an overload of `@__testing()`) that emits a
warning. This allows us to emit compile-time warnings from contexts
where only attributes are semantically valid.

We need this in particular for test content records because their
section info is comprised of a big `IfConfigDecl` node and platforms
that aren't covered (i.e. the `#else` clause) don't have a way to emit a
diagnostic that says "we need to fix this platform's Swift Testing
port!" like we can do in other contexts with `#warning()`:

```swift
#if os(macOS) || os(iOS) || os(watchOS) || os(tvOS) || os(visionOS)
@_section("__DATA_CONST,__swift5_tests")
#elseif os(Linux) || os(FreeBSD) || os(OpenBSD) || os(Android) || os(WASI)
@_section("swift5_tests")
#elseif os(Windows)
@_section(".sw5test$B")
#else
// ⚠️ #warning isn't valid here, what do we do!?
#endif
@_used
private static let record: __TestContentRecord = (...)
```

### Checklist:

- [x] Code and documentation should follow the style of the [Style
Guide](https://github.com/apple/swift-testing/blob/main/Documentation/StyleGuide.md).
- [x] If public symbols are renamed or modified, DocC references should
be updated.

Author: grynspan

Sources/Testing/Test+Macro.swift

@@ -499,12 +499,24 @@ extension Test {
 /// - Note: This macro has compile-time effects _only_ and should not affect a
 ///   compiled test target.
 ///
-/// - Warning: This macro is used to implement other macros declared by the testing
-///   library. Do not use it directly.
+/// - Warning: This macro is used to implement other macros declared by the
+///   testing library. Do not use it directly.
 @attached(peer) public macro __testing(
   semantics arguments: _const String...
 ) = #externalMacro(module: "TestingMacros", type: "PragmaMacro")
 
+/// A macro used similarly to `#warning()` but in a position where only an
+/// attribute is valid.
+///
+/// - Parameters:
+///   - message: A string to emit as a warning.
+///
+/// - Warning: This macro is used to implement other macros declared by the
+///   testing library. Do not use it directly.
+@attached(peer) public macro __testing(
+  warning message: _const String
+) = #externalMacro(module: "TestingMacros", type: "PragmaMacro")
+
 // MARK: - Helper functions
 
 /// A function that abstracts away whether or not the `try` keyword is needed on

Sources/TestingMacros/PragmaMacro.swift

@@ -17,7 +17,9 @@ public import SwiftSyntaxMacros
 ///
 /// - `@__testing(semantics: "nomacrowarnings")`: suppress warning diagnostics
 ///   generated by macros. (The implementation of this use case is held in trust
-///   at ``MacroExpansionContext/areWarningsSuppressed``.
+///   at ``MacroExpansionContext/areWarningsSuppressed``.)
+/// - `@__testing(warning: "...")`: emits `"..."` as a diagnostic message
+///   attributed to the node to which the attribute is attached.
 ///
 /// This type is used to implement the `@__testing` attribute macro. Do not use
 /// it directly.
@@ -27,6 +29,17 @@ public struct PragmaMacro: PeerMacro, Sendable {
     providingPeersOf declaration: some DeclSyntaxProtocol,
     in context: some MacroExpansionContext
   ) throws -> [DeclSyntax] {
+    if case let .argumentList(arguments) = node.arguments,
+       arguments.first?.label?.textWithoutBackticks == "warning" {
+      let targetNode = Syntax(declaration)
+      let messages = arguments
+        .map(\.expression)
+        .compactMap { $0.as(StringLiteralExprSyntax.self) }
+        .compactMap(\.representedLiteralValue)
+        .map { DiagnosticMessage(syntax: targetNode, message: $0, severity: .warning) }
+      context.diagnose(messages)
+    }
+
     return []
   }
 

Tests/TestingMacrosTests/PragmaMacroTests.swift

@@ -18,12 +18,25 @@ import SwiftSyntax
 struct PragmaMacroTests {
   @Test func findSemantics() throws {
     let node = """
-      @Testing.__testing(semantics: "abc123")
-      @__testing(semantics: "def456")
-      let x = 0
+    @Testing.__testing(semantics: "abc123")
+    @__testing(semantics: "def456")
+    let x = 0
     """ as DeclSyntax
     let nodeWithAttributes = try #require(node.asProtocol((any WithAttributesSyntax).self))
     let semantics = semantics(of: nodeWithAttributes)
     #expect(semantics == ["abc123", "def456"])
   }
+
+  @Test func warningGenerated() throws {
+    let sourceCode = """
+    @__testing(warning: "abc123")
+    let x = 0
+    """
+
+    let (_, diagnostics) = try parse(sourceCode)
+    #expect(diagnostics.count == 1)
+    #expect(diagnostics[0].message == "abc123")
+    #expect(diagnostics[0].diagMessage.severity == .warning)
+    #expect(diagnostics[0].node.is(VariableDeclSyntax.self))
+  }
 }

Tests/TestingMacrosTests/TestSupport/Parse.swift

@@ -30,6 +30,7 @@ fileprivate let allMacros: [String: any Macro.Type] = [
   "Suite": SuiteDeclarationMacro.self,
   "Test": TestDeclarationMacro.self,
   "Tag": TagMacro.self,
+  "__testing": PragmaMacro.self,
 ]
 
 func parse(_ sourceCode: String, activeMacros activeMacroNames: [String] = [], removeWhitespace: Bool = false) throws -> (sourceCode: String, diagnostics: [Diagnostic]) {

Tests/TestingTests/MiscellaneousTests.swift

@@ -598,6 +598,8 @@ struct MiscellaneousTests {
     @_section("swift5_tests")
 #elseif os(Windows)
     @_section(".sw5test$B")
+#else
+    @__testing(warning: "Platform-specific implementation missing: test content section name unavailable")
 #endif
     @_used
     private static let record: __TestContentRecord = (