Provide an ABI-friendly entry point function that takes/produces JSON. (#360)

This PR introduces an **experimental** function, intended to eventually
become part of our stable ABI, named `swt_copyABIEntryPoint_v0()`. This
function can be looked up at runtime and used to hook into the testing
library when a test target is loaded into the current process. It takes
a JSON-encoded structure as input and yields JSON-encoded events/event
contexts via a callback.

The input is encoded from a type we've tentatively named
`__CommandLineArguments_v0`. This type conforms to `Codable` and
represents the parsed command-line arguments that the package can
understand. Normally, swift-testing will construct an instance of this
type from the command-line arguments to the current process, but a
caller can pass in a different instance to the ABI entry point instead.

The output consists of `Event.Snapshot` and `Event.Context.Snapshot`
values encoded in a single JSON object. The format of this JSON is
identical to what is emitted when `--experimental-event-stream-output`
is specified at the command line.

`__swiftPMEntryPoint()` has also been modified to use the same
`__CommandLineArguments_v0` type as input and as much of the same
implementation as possible.

Because trying to load a Swift function dynamically at runtime is Hard™,
`swt_copyABIEntryPoint_v0()` is a C function that yields the "real"
Swift function. This indirection also gives us the flexibility to
produce a thick Swift closure rather than a thin function.

> [!WARNING]
> The signature of structure of `swt_copyABIEntryPoint_v0`, the
structure of `__CommandLineArguments_v0`, how it encodes to/from JSON,
and all other details about it are still subject to change. The hope is
that it becomes a stable ABI surface _eventually_, but we're not there
yet. :)

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

@@ -0,0 +1,124 @@
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2023 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) && !SWT_NO_ABI_ENTRY_POINT
+/// The type of the entry point to the testing library used by tools that want
+/// to remain version-agnostic regarding the testing library.
+///
+/// - Parameters:
+///   - argumentsJSON: A buffer to memory representing the JSON encoding of an
+///     instance of `__CommandLineArguments_v0`. If `nil`, a new instance is
+///     created from the command-line arguments to the current process.
+///   - eventHandler: An event handler to which is passed a buffer to memory
+///     representing each event and its context, as with ``Event/Handler``, but
+///     encoded as JSON.
+///
+/// - Returns: The result of invoking the testing library. The type of this
+///   value is subject to change.
+///
+/// This function examines the command-line arguments to the current process
+/// and then invokes available tests in the current process.
+///
+/// - Warning: This function's signature and the structure of its JSON inputs
+///   and outputs have not been finalized yet.
+@_spi(ForToolsIntegrationOnly)
+public typealias ABIEntryPoint_v0 = @Sendable (
+  _ argumentsJSON: UnsafeRawBufferPointer?,
+  _ eventHandler: @escaping @Sendable (_ eventAndContextJSON: UnsafeRawBufferPointer) -> Void
+) async -> CInt
+
+/// Get the entry point to the testing library used by tools that want to remain
+/// version-agnostic regarding the testing library.
+///
+/// - Parameters:
+///   - outEntryPoint: Uninitialized memory large enough to hold an instance of
+///     ``ABIEntryPoint_v0``. On return, a pointer to an instance of that type
+///     representing the ABI-stable entry point to the testing library. The
+///     caller owns this memory and is responsible for deinitializing and
+///     deallocating it when done.
+///
+/// This function can be used by tools that do not link directly to the testing
+/// library and wish to invoke tests in a binary that has been loaded into the
+/// current process. The function is emitted into the binary under the name
+/// `"swt_copyABIEntryPoint_v0"` and can be dynamically looked up at runtime
+/// using `dlsym()` or a platform equivalent.
+///
+/// The function stored at `outEntryPoint` can be thought of as equivalent to
+/// `swift test --experimental-event-stream-output` except that, instead of
+/// streaming events to a named pipe or file, it streams them to a callback.
+///
+/// - Warning: This function's signature and the structure of its JSON inputs
+///   and outputs have not been finalized yet.
+@_cdecl("swt_copyABIEntryPoint_v0")
+@usableFromInline
+func abiEntryPoint_v0(_ outEntryPoint: UnsafeMutableRawPointer) {
+  outEntryPoint.initializeMemory(as: ABIEntryPoint_v0.self) { argumentsJSON, eventHandler in
+    let args = try! argumentsJSON.map { argumentsJSON in
+      try JSON.decode(__CommandLineArguments_v0.self, from: argumentsJSON)
+    }
+
+    let eventHandler = eventHandlerForStreamingEvents_v0(to: eventHandler)
+    return await entryPoint(passing: args, eventHandler: eventHandler)
+  }
+}
+#endif
+
+// MARK: - Experimental event streaming
+
+#if canImport(Foundation) && (!SWT_NO_FILE_IO || !SWT_NO_ABI_ENTRY_POINT)
+/// A type containing an event snapshot and snapshots of the contents of an
+/// event context suitable for streaming over JSON.
+///
+/// This function is not part of the public interface of the testing library.
+/// External adopters are not necessarily written in Swift and are expected to
+/// decode the JSON produced for this type in implementation-specific ways.
+struct EventAndContextSnapshot {
+  /// A snapshot of the event.
+  var event: Event.Snapshot
+
+  /// A snapshot of the event context.
+  var eventContext: Event.Context.Snapshot
+}
+
+extension EventAndContextSnapshot: Codable {}
+
+/// Create an event handler that encodes events as JSON and forwards them to an
+/// ABI-friendly event handler.
+///
+/// - Parameters:
+///   - eventHandler: The event handler to forward events to. See
+///     ``ABIEntryPoint_v0`` for more information.
+///
+/// - Returns: An event handler.
+///
+/// The resulting event handler outputs data as JSON. For each event handled by
+/// the resulting event handler, a JSON object representing it and its
+/// associated context is created and is passed to `eventHandler`. These JSON
+/// objects are guaranteed not to contain any ASCII newline characters (`"\r"`
+/// or `"\n"`).
+///
+/// Note that `_eventHandlerForStreamingEvents_v0(toFileAtPath:)` calls this
+/// function and performs additional postprocessing before writing JSON data.
+func eventHandlerForStreamingEvents_v0(
+  to eventHandler: @escaping @Sendable (_ eventAndContextJSON: UnsafeRawBufferPointer) -> Void
+) -> Event.Handler {
+  return { event, context in
+    let snapshot = EventAndContextSnapshot(
+      event: Event.Snapshot(snapshotting: event),
+      eventContext: Event.Context.Snapshot(snapshotting: context)
+    )
+    try? JSON.withEncoding(of: snapshot) { eventAndContextJSON in
+      eventAndContextJSON.withUnsafeBytes { eventAndContextJSON in
+        eventHandler(eventAndContextJSON)
+      }
+    }
+  }
+}
+#endif