Split .bug() into two taking a URL or a number.

This PR changes the initializers for `.bug()` from ones taking an undecorated
and unspecified "identifier" to ones taking either a URL (as a string) or a
numeric ID ("bug number.")

The existing interface is ambiguous to tools authors seeking to integrate with
it. They must treat _every_ bug as potentially containing a URL with fallback
paths if a bug's ID cannot be parsed as a URL. By splitting URLs and numbers up
into two separate properties, tools authors can provide reliable, distinct
interfaces for bugs known by number vs. those known by URL.

Author: grynspan

Sources/Testing/Testing.docc/AssociatingBugs.md

@@ -25,9 +25,13 @@ specific bugs with tests that reproduce them or verify they are fixed.
 
 ## Associate a bug with a test
 
-To associate a bug with a test, use the ``Trait/bug(_:_:)-2u8j9`` or
-``Trait/bug(_:_:)-7mo2w`` function. The first argument to this function is the
-bug's _identifier_ in its bug-tracking system:
+To associate a bug with a test, use one of these functions:
+- ``Trait/bug(url:_:)``
+- ``Trait/bug(_:url:_:)-7f1e4``
+- ``Trait/bug(_:url:_:)-41twe``
+
+The first argument to these functions is the bug's _identifier_ in its
+bug-tracking system:
 
 ```swift
 @Test("Food truck engine works", .bug("12345"), .bug(67890))
@@ -43,7 +47,7 @@ specified as a string, it must be parseable as an unsigned integer or as a URL.
 For more information on the formats recognized by the testing library, see
 <doc:BugIdentifiers>.
 
-## Add comments to associated bugs
+## Add titles to associated bugs
 
 A bug identifier may be insufficient to uniquely and clearly identify a bug
 associated with a test. Bug trackers universally provide a "title" field for

Sources/Testing/Testing.docc/BugIdentifiers.md

@@ -14,37 +14,30 @@ How the testing library interprets bug identifiers provided by developers.
 
 ## Overview
 
-As a convenience, the testing library assumes that bug identifiers with specific
-formats are associated with some common bug-tracking systems.
+The testing library supports two distinct ways to identify a bug:
+
+1. A URL linking to more information about the bug; and
+2. A unique identifier in the bug's associated bug-tracking system.
 
 - Note: "Bugs" as described in this document may also be referred to as
-  "issues." To avoid confusion with the ``Issue`` type in the testing library,
-  this document consistently refers to them as "bugs."
-
-## Recognized formats
-
-- If the bug identifier begins with `"rdar:"`, it is assumed to represent a bug
-  filed with Apple's Radar system.
-- If the bug identifier can be parsed as a URL according to
-  [RFC 3986](https://www.ietf.org/rfc/rfc3986.txt), it is assumed to represent
-  an issue tracked at that URL.
-- If the bug identifier begins with `"FB"` and the rest of it can be parsed as
-  an unsigned integer, it is assumed to represent a bug filed with the
-  [Apple Feedback Assistant](https://feedbackassistant.apple.com).
-- If the bug identifier can be parsed as an unsigned integer, it is assumed to
-  represent an issue with that numeric identifier in an unspecified bug-tracking
-  system.
-- All other bug identifiers are considered invalid and will cause the compiler
-  to generate an error at compile time.
+"issues." To avoid confusion with the ``Issue`` type in the testing library,
+this document consistently refers to them as "bugs."
 
-<!--
-Possible additional formats we could recognize (which would require special
-handling to detect:
+A bug may have both an associated URL _and_ an associated unique identifier. It
+must have at least one or the other in order for the testing library to be able
+to interpret it correctly.
 
-- If the bug identifier begins with `"#"` and can be parsed as a positive
-  integer, it is assumed to represent a [GitHub](https://github.com) issue in
-  the same repository as the test.
--->
+To create an instance of ``Bug`` with a URL, use the ``Trait/bug(url:_:)``
+trait. At compile time, the testing library will validate that the given string
+can be parsed as a URL according to [RFC 3986](https://www.ietf.org/rfc/rfc3986.txt).
+
+To create an instance of ``Bug`` with a bug's unique identifier, use the
+``Trait/bug(_:url:_:)-7f1e4`` trait. The testing library does not require that
+a bug's unique identifier match any particular format, but will interpret
+unique identifiers starting with `"FB"` as referring to bugs tracked with the
+[Apple Feedback Assistant](https://feedbackassistant.apple.com). For
+convenience, you can also directly pass an integer as a bug's identifier using
+``Trait/bug(_:url:_:)-41twe``.
 
 ## Examples
 
@@ -53,10 +46,12 @@ handling to detect:
 | `.bug(12345)` | Yes | None |
 | `.bug("12345")` | Yes | None |
 | `.bug("Things don't work")` | **No** | None |
-| `.bug("rdar:12345")` | Yes | Apple Radar |
-| `.bug("https://github.com/apple/swift/pull/12345")` | Yes | [GitHub Issues for the Swift project](https://github.com/apple/swift/issues) |
-| `.bug("https://bugs.webkit.org/show_bug.cgi?id=12345")` | Yes | [WebKit Bugzilla](https://bugs.webkit.org/) |
+| `.bug(12345, "Things don't work")` | Yes | None |
+| `.bug(url: "rdar:12345")` | Yes | Apple Radar |
+| `.bug(url: "https://github.com/apple/swift/pull/12345")` | Yes | [GitHub Issues for the Swift project](https://github.com/apple/swift/issues) |
+| `.bug(url: "https://bugs.webkit.org/show_bug.cgi?id=12345")` | Yes | [WebKit Bugzilla](https://bugs.webkit.org/) |
 | `.bug("FB12345")` | Yes | Apple Feedback Assistant | <!-- SEE ALSO: rdar://104582015 -->
+| `.bug("12345", url: "rdar:12345")` | Yes | Apple Radar |
 <!--
 | `.bug("#12345")` | Yes | GitHub Issues for the current repository (if hosted there) |
 -->

Sources/Testing/Testing.docc/EnablingAndDisabling.md

@@ -83,8 +83,14 @@ func isCold() async throws { ... }
 ```
 
 If a test is disabled because of a problem for which there is a corresponding
-bug report, you can use the ``Trait/bug(_:_:)-2u8j9`` or
-``Trait/bug(_:_:)-7mo2w`` function to show the relationship:
+bug report, you can use one of these functions to show the relationship
+between the test and the bug report:
+
+- ``Trait/bug(url:_:)``
+- ``Trait/bug(_:url:_:)-7f1e4``
+- ``Trait/bug(_:url:_:)-41twe``
+
+For example, the following test cannot run due to bug number `"12345"`:
 
 ```swift
 @Test(
@@ -97,8 +103,8 @@ func isCold() async throws { ... }
 ```
 
 If a test has multiple conditions applied to it, they must _all_ pass for it to
-run. Otherwise, the test notes the first condition to fail as the reason the test
-is skipped.
+run. Otherwise, the test notes the first condition to fail as the reason the
+test is skipped.
 
 ## Handle complex conditions
 

Sources/Testing/Testing.docc/Traits.md

@@ -46,8 +46,9 @@ HIDDEN: .serialized is experimental SPI pending feature review.
 - <doc:AssociatingBugs>
 - <doc:BugIdentifiers>
 - ``Tag()``
-- ``Trait/bug(_:_:)-2u8j9``
-- ``Trait/bug(_:_:)-7mo2w``
+- ``Trait/bug(url:_:)``
+- ``Trait/bug(_:url:_:)-7f1e4``
+- ``Trait/bug(_:url:_:)-41twe``
 
 ### Creating custom traits
 

Sources/Testing/Testing.docc/Traits/Trait.md

@@ -31,8 +31,9 @@ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 
 ### Associating bugs
 
-- ``Trait/bug(_:_:)-2u8j9``
-- ``Trait/bug(_:_:)-7mo2w``
+- ``Trait/bug(url:_:)``
+- ``Trait/bug(_:url:_:)-7f1e4``
+- ``Trait/bug(_:url:_:)-41twe``
 
 ### Adding information to tests
 - ``Trait/comments``

Sources/Testing/Traits/Bug.swift

@@ -12,32 +12,37 @@
 ///
 /// To add this trait to a test, use one of the following functions:
 ///
-/// - ``Trait/bug(_:_:)-86mmm``
-/// - ``Trait/bug(_:_:)-3hsi5``
+/// - ``Trait/bug(url:_:)``
+/// - ``Trait/bug(_:url:_:)-7f1e4``
+/// - ``Trait/bug(_:url:_:)-41twe``
 public struct Bug {
-  /// The identifier of this bug in the associated bug-tracking system.
+  /// A unique identifier in this bug's associated bug-tracking system, if
+  /// available.
   ///
   /// For more information on how the testing library interprets bug
   /// identifiers, see <doc:BugIdentifiers>.
-  public var identifier: String
+  public var id: String?
 
-  /// An optional, user-specified comment describing this trait.
-  public var comment: Comment?
+  /// A URL linking to more information about the bug, if available.
+  ///
+  /// The value of this property represents a URL conforming to
+  /// [RFC 3986](https://www.ietf.org/rfc/rfc3986.txt).
+  public var url: String?
+
+  /// The human-readable title of the bug, if specified by the test author.
+  public var title: Comment?
 }
 
-// MARK: - Equatable, Hashable, Comparable
+// MARK: - Equatable, Hashable
 
-extension Bug: Equatable, Hashable, Comparable {
+extension Bug: Equatable, Hashable {
   public static func ==(lhs: Self, rhs: Self) -> Bool {
-    lhs.identifier == rhs.identifier
+    lhs.url == rhs.url && lhs.id == rhs.id
   }
 
   public func hash(into hasher: inout Hasher) {
-    hasher.combine(identifier)
-  }
-
-  public static func <(lhs: Self, rhs: Self) -> Bool {
-    lhs.identifier < rhs.identifier
+    hasher.combine(url)
+    hasher.combine(id)
   }
 }
 
@@ -49,35 +54,49 @@ extension Bug: Codable {}
 
 extension Bug: TestTrait, SuiteTrait {
   public var comments: [Comment] {
-    Array(comment)
+    Array(title)
   }
 }
 
 extension Trait where Self == Bug {
   /// Construct a bug to track with a test.
   ///
   /// - Parameters:
-  ///   - identifier: The identifier of this bug in the associated bug-tracking
-  ///     system. For more information on how this value is interpreted, see the
-  ///     documentation for ``Bug``.
-  ///   - comment: An optional, user-specified comment describing this trait.
+  ///   - url: A URL referring to this bug in the associated bug-tracking
+  ///     system.
+  ///   - title: Optionally, the human-readable title of the bug.
+  ///
+  /// - Returns: An instance of ``Bug`` representing the specified bug.
+  public static func bug(url: _const String, _ title: Comment? = nil) -> Self {
+    Self(url: url, title: title)
+  }
+
+  /// Construct a bug to track with a test.
+  ///
+  /// - Parameters:
+  ///   - id: The unique identifier of this bug in its associated bug-tracking
+  ///     system.
+  ///   - url: A URL referring to this bug in the associated bug-tracking
+  ///     system.
+  ///   - title: Optionally, the human-readable title of the bug.
   ///
   /// - Returns: An instance of ``Bug`` representing the specified bug.
-  public static func bug(_ identifier: String, _ comment: Comment? = nil) -> Self {
-    Self(identifier: identifier, comment: comment)
+  public static func bug(_ id: some Numeric, url: _const String? = nil, _ title: Comment? = nil) -> Self {
+    Self(id: String(describing: id), url: url, title: title)
   }
 
   /// Construct a bug to track with a test.
   ///
   /// - Parameters:
-  ///   - identifier: The identifier of this bug in the associated bug-tracking
-  ///     system. For more information on how this value is interpreted, see the
-  ///     documentation for ``Bug``.
-  ///   - comment: An optional, user-specified comment describing this trait.
+  ///   - id: The unique identifier of this bug in its associated bug-tracking
+  ///     system.
+  ///   - url: A URL referring to this bug in the associated bug-tracking
+  ///     system.
+  ///   - title: Optionally, the human-readable title of the bug.
   ///
   /// - Returns: An instance of ``Bug`` representing the specified bug.
-  public static func bug(_ identifier: some Numeric, _ comment: Comment? = nil) -> Self {
-    Self(identifier: String(describing: identifier), comment: comment)
+  public static func bug(_ id: _const String, url: _const String? = nil, _ title: Comment? = nil) -> Self {
+    Self(id: id, url: url, title: title)
   }
 }
 

Sources/Testing/Traits/Comment.swift

@@ -18,7 +18,8 @@
 /// or `@Suite` attribute. See <doc:AddingComments> for more details.
 ///
 /// - Note: This type is not intended to reference bugs related to a test.
-///   Instead, use ``Trait/bug(_:_:)-2u8j9`` or ``Trait/bug(_:_:)-7mo2w``.
+///   Instead, use ``Trait/bug(url:_:)``, ``Trait/bug(_:url:_:)-7f1e4``, or
+///   ``Trait/bug(_:url:_:)-41twe``.
 public struct Comment: RawRepresentable, Sendable {
   /// The single comment string contained in this instance.
   ///
@@ -121,7 +122,8 @@ extension Trait where Self == Comment {
   ///   comment.
   ///
   /// - Note: This function is not intended to reference bugs related to a test.
-  ///   Instead, use ``Trait/bug(_:_:)-2u8j9`` or ``Trait/bug(_:_:)-7mo2w``.
+  ///   Instead, use ``Trait/bug(url:_:)``, ``Trait/bug(_:url:_:)-7f1e4``,
+  ///   or ``Trait/bug(_:url:_:)-41twe``.
   public static func comment(_ comment: String) -> Self {
     Self(rawValue: comment, kind: .trait)
   }

Sources/TestingMacros/Support/DiagnosticMessage+Diagnosing.swift

@@ -108,29 +108,14 @@ private func _diagnoseIssuesWithTagsTrait(_ traitExpr: FunctionCallExprSyntax, a
 ///   - attribute: The `@Test` or `@Suite` attribute.
 ///   - context: The macro context in which the expression is being parsed.
 private func _diagnoseIssuesWithBugTrait(_ traitExpr: FunctionCallExprSyntax, addedTo attribute: AttributeSyntax, in context: some MacroExpansionContext) {
-  // If the first argument to the .bug() trait is unlabelled and a string
-  // literal, check that it can be parsed as a URL or at least as an integer.
-  guard let arg = traitExpr.arguments.first.map(Argument.init),
-        arg.label == nil,
-        let stringLiteralExpr = arg.expression.as(StringLiteralExprSyntax.self),
-        let urlString = stringLiteralExpr.representedLiteralValue else {
-    return
+  // If there is an argument to the .bug() trait labelled "url:" and its value
+  // is a string literal, check that it can be parsed the way we expect.
+  let urlArgIndex = traitExpr.arguments.firstIndex { argument in
+    argument.label?.textWithoutBackticks == "url"
   }
-
-  if UInt64(urlString) != nil {
-    // The entire URL string can be parsed as an integer, so allow it. Although
-    // the testing library prefers valid URLs here, some bug-tracking systems
-    // might not provide URLs, or might provide excessively long URLs, so we
-    // allow numeric identifiers as a fallback.
-    return
-  }
-
-  if urlString.count > 3 && urlString.starts(with: "FB") && UInt64(urlString.dropFirst(2)) != nil {
-    // The string appears to be of the form "FBnnn...". Such strings are used by
-    // Apple to indicate issues filed using Feedback Assistant. Although we
-    // don't want to special-case every possible bug-tracking system out there,
-    // Feedback Assistant is very important to Apple so we're making an
-    // exception for it.
+  guard let urlArgIndex,
+        let stringLiteralExpr = traitExpr.arguments[urlArgIndex].expression.as(StringLiteralExprSyntax.self),
+        let urlString = stringLiteralExpr.representedLiteralValue else {
     return
   }
 

Sources/TestingMacros/Support/DiagnosticMessage.swift

@@ -567,7 +567,7 @@ struct DiagnosticMessage: SwiftDiagnostics.DiagnosticMessage {
     return Self(
       syntax: Syntax(urlExpr),
       message: #"URL "\#(urlString)" is invalid and cannot be used with trait '\#(traitName.trimmed)' in attribute \#(_macroName(attribute))"#,
-      severity: .error,
+      severity: .warning,
       fixIts: [
         FixIt(
           message: MacroExpansionFixItMessage(#"Replace "\#(urlString)" with URL"#),

Sources/_Testing_Foundation/Traits/Bug+URL.swift

@@ -0,0 +1,33 @@
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2024 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+// See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+//
+
+#if canImport(Foundation)
+@_spi(Experimental) @_spi(ForToolsIntegrationOnly) public import Testing
+public import Foundation
+
+extension Trait where Self == Bug {
+  /// Construct a bug to track with a test.
+  ///
+  /// - Parameters:
+  ///   - url: A URL referring to this bug in the associated bug-tracking
+  ///     system.
+  ///   - title: Optionally, the human-readable title of the bug.
+  ///
+  /// - Returns: An instance of ``Bug`` representing the specified bug.
+  public static func bug(url: URL, _ title: Comment? = nil) -> Self {
+    // The factory functions in Bug.swift take _const strings in order to help
+    // enforce URL validation, so work around it by creating an instance with a
+    // blank ID and replacing it.
+    var result = Bug.bug(url: "")
+    result.url = url.absoluteString
+    return result
+  }
+}
+#endif