Special-case FileHandle(forWritingAtPath: "CONOUT$") on Windows. (#654)

This PR special-cases calls to `FileHandle.init(forWritingAtPath:)` when
passed `"CONOUT$"` (the reserved "console output" file) on Windows such
that it does not open a new file but just returns a copy of `.stdout`
instead.

This change is necessary because, on Windows, opening and locking
`"CONOUT$"` does not lock `stdout` (they're considered entirely
different files) and output written to `"CONOUT$"` is wrapped at the
console's column limit even though it's being written as binary data.
The VSCode Swift plugin authors would like to be able to specify writing
the JSON event stream to `"CONOUT$"`, but the observed behaviour is
stopping them from doing so.

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

@@ -52,6 +52,21 @@ struct FileHandle: ~Copyable, Sendable {
   /// - Throws: Any error preventing the stream from being opened.
   init(atPath path: String, mode: String) throws {
 #if os(Windows)
+    // Special-case CONOUT$ to map to stdout. This way, if somebody specifies
+    // CONOUT$ as the target path for XML or JSON output from `swift test`,
+    // output will be correctly interleaved with writes to `stdout`. If we don't
+    // do this, the file will open successfully but will be opened in text mode
+    // (even if we ask for binary mode), will wrap at the virtual console's
+    // column limit, and won't share a file lock with the C `stdout` handle.
+    //
+    // To our knowledge, this sort of special-casing is not required on
+    // POSIX-like platforms (i.e. when opening "/dev/stdout"), but it can be
+    // adapted for use there if some POSIX-like platform does need it.
+    if path == "CONOUT$" && mode.contains("w") {
+      self = .stdout
+      return
+    }
+
     // Windows deprecates fopen() as insecure, so call _wfopen_s() instead.
     let fileHandle = try path.withCString(encodedAs: UTF16.self) { path in
       try mode.withCString(encodedAs: UTF16.self) { mode in