Add enforcement for returned issues of kind 'apiMisused' as described in proposal

Author: stmontgomery

Sources/Testing/Traits/IssueHandlingTrait.swift

@@ -121,9 +121,20 @@ extension IssueHandlingTrait: TestScoping {
       }
 
       if let newIssue {
-        // Prohibit assigning the issue's kind to system.
-        if case .system = newIssue.kind {
+        // Validate the value of the returned issue's 'kind' property.
+        switch (issue.kind, newIssue.kind) {
+        case (_, .system):
+          // Prohibited by ST-0011.
           preconditionFailure("Issue returned by issue handling closure cannot have kind 'system': \(newIssue)")
+        case (.apiMisused, .apiMisused):
+          // This is permitted, but must be listed explicitly before the
+          // wildcard case below.
+          break
+        case (_, .apiMisused):
+          // Prohibited by ST-0011.
+          preconditionFailure("Issue returned by issue handling closure cannot have kind 'apiMisused' when the passed-in issue had a different kind: \(newIssue)")
+        default:
+          break
         }
 
         var event = event

Tests/TestingTests/Traits/IssueHandlingTraitTests.swift

@@ -216,6 +216,27 @@ struct IssueHandlingTraitTests {
     }.run(configuration: configuration)
   }
 
+  @Test("An API misused issue can be returned by issue handler closure when the original issue had that kind")
+  func returningAPIMisusedIssue() async throws {
+    var configuration = Configuration()
+    configuration.eventHandler = { event, context in
+      if case let .issueRecorded(issue) = event.kind, case .unconditional = issue.kind {
+        issue.record()
+      }
+    }
+
+    let handler = IssueHandlingTrait.compactMapIssues { issue in
+      guard case .apiMisused = issue.kind else {
+        return Issue.record("Expected an issue of kind 'apiMisused': \(issue)")
+      }
+      return issue
+    }
+
+    await Test(handler) {
+      Issue(kind: .apiMisused).record()
+    }.run(configuration: configuration)
+  }
+
 #if !SWT_NO_EXIT_TESTS
   @Test("Disallow assigning kind to .system")
   func disallowAssigningSystemKind() async throws {
@@ -229,5 +250,18 @@ struct IssueHandlingTraitTests {
       }.run()
     }
   }
+
+  @Test("Disallow assigning kind to .apiMisused")
+  func disallowAssigningAPIMisusedKind() async throws {
+    await #expect(processExitsWith: .failure) {
+      await Test(.compactMapIssues { issue in
+        var issue = issue
+        issue.kind = .apiMisused
+        return issue
+      }) {
+        Issue.record("A non-system issue")
+      }.run()
+    }
+  }
 #endif
 }