Add a C-callable "gestalt" function for querying some basic info. (#1596)

This PR adds an exported C function that lets callers query some info
that may be necessary to gather before those callers can reliably invoke
the testing library's ABI-stable entry point function.

This function is _not_ meant to be a general-purpose querying function,
nor is it intended for use by tools authors. Rather, it is useful if
you're writing code that works with the JSON event stream and needs to
know how to communicate with the testing library. In particular, a
caller would need to know the range of supported JSON schema versions.

### 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/ABI/ABI.swift

@@ -8,6 +8,8 @@
 // See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 //
 
+private import _TestingInternals
+
 /// A namespace for ABI symbols.
 @_spi(ForToolsIntegrationOnly)
 public enum ABI: Sendable {}
@@ -209,3 +211,57 @@ extension ABI {
     }
   }
 }
+
+// MARK: -
+
+/// The set of keys accepted by `_swift_testing_copyMetadataValue(_:_:)`.
+private enum _MetadataKey: String, Sendable, CaseIterable {
+  /// The minimum supported ABI version.
+  case minimumSupportedABIVersion = "_minimumSupportedABIVersion"
+
+  /// The maximum supported ABI version.
+  case maximumSupportedABIVersion = "_maximumSupportedABIVersion"
+}
+
+/// An exported C function that allows querying information about the testing
+/// library without running any tests.
+///
+/// - Parameters:
+///   - key: The name of the value of interest. See the `_MetadataKey`
+///     enumeration for a list of supported values.
+///   - reserved: Reserved for future use. Pass `0`.
+///
+/// - Returns: A pointer to a UTF-8 C string containing the JSON representation
+///   of the requested information, or `nil` if that information was not
+///   available. The caller is responsible for freeing this memory with C's
+///   `free()` function.
+#if compiler(>=6.3)
+@c(_swift_testing_copyMetadataValue)
+#else
+@_cdecl("_swift_testing_copyMetadataValue")
+#endif
+@usableFromInline func _swift_testing_copyMetadataValue(_ key: UnsafePointer<CChar>, _ reserved: UInt) -> UnsafeMutablePointer<CChar>? {
+  func copyJSON(for value: some Encodable) -> UnsafeMutablePointer<CChar>? {
+    try? JSON.withEncoding(of: value) { json in
+      json.withMemoryRebound(to: CChar.self) { json in
+        // The JSON produced by Foundation is not null-terminated, so to avoid
+        // an intermediate copy we call `calloc()` instead of `strdup()`.
+        let result = calloc(json.count + 1, MemoryLayout<CChar>.stride)
+        guard let result = result?.assumingMemoryBound(to: CChar.self) else {
+          return nil
+        }
+        result.initialize(from: json.baseAddress!, count: json.count)
+        return result
+      }
+    }
+  }
+
+  switch String(validatingCString: key).flatMap(_MetadataKey.init) {
+  case .minimumSupportedABIVersion:
+    return copyJSON(for: ABI.v0.versionNumber)
+  case .maximumSupportedABIVersion:
+    return copyJSON(for: ABI.CurrentVersion.versionNumber)
+  case nil:
+    return nil
+  }
+}

Tests/TestingTests/ABIEntryPointTests.swift

@@ -184,6 +184,22 @@ struct ABIEntryPointTests {
     }
   }
 #endif
+
+  func decodeMetadataValue<T>(forKey key: String, ofType type: T.Type) throws -> T where T: Decodable {
+    let cString = try #require(_swift_testing_copyMetadataValue(key, 0))
+    defer {
+      free(cString)
+    }
+    let byteCount = strlen(cString)
+    return try JSON.decode(type, from: UnsafeRawBufferPointer(start: cString, count: byteCount))
+  }
+
+  @Test func copyMetadataValue() throws {
+    let lowerBound = try decodeMetadataValue(forKey: "_minimumSupportedABIVersion", ofType: ABI.VersionNumber.self)
+    #expect(lowerBound == ABI.v0.versionNumber)
+    let upperBound = try decodeMetadataValue(forKey: "_maximumSupportedABIVersion", ofType: ABI.VersionNumber.self)
+    #expect(upperBound == ABI.CurrentVersion.versionNumber)
+  }
 }
 
 #if !SWT_NO_DYNAMIC_LINKING