Create the --output directory up front instead of failing late on index.html (fixes #446) - #471

Fixes #446.

The bug

$ xchtmlreport TestResults.xcresult --output /some/missing/dir/report
... minutes of parsing, rendering and attachment exporting ...
Error: An error has occured while creating the report
Error: The file “index.html” doesn’t exist.
$ echo $?
1

Neither line names the real problem. The failure is the final
html.write(toFile:) in run(), so it arrives after all the work is done —
and in linking mode after payloads have already been exported into the bundle.
index.html is a red herring: the file that doesn't exist is the directory
above it. This is what made the first scheduled toolchain-drift run (#444) look
like toolchain drift.

The fix

Create the output directory, intermediates included, before anything else
happens — before the Summary is built, before parsing, rendering or
exporting. Create-by-default is what every CLI this one sits next to does, and
it is a no-op on the overwhelmingly common path where the directory already
exists.

When the directory genuinely cannot be created — no write permission on the
parent, a file in the way — that is a usage error, not a degraded report:
it throws ValidationError, so it exits 64 like the tool's other usage
errors, never 3, which is reserved for collected faults. The message names the
path and the reason, and arrives before any work:

$ xchtmlreport TestResults.xcresult --output /read-only-dir/report
Error: Could not create output directory /read-only-dir/report: You don’t have
permission to save the file “report” in the folder “read-only-dir”.
Usage: xchtmlreport [<options>] [<results> ...]
$ echo $?
64

The An error has occured while creating the report string (typo included) is
untouched — this fix makes that path unreachable for a missing output
directory, and rewording it is a separate concern.

The #445 workaround comes out

.github/workflows/toolchain-drift.yml gained a mkdir -p "$RUNNER_TEMP/drift-report"
in #445 specifically to stop this bug from being misreported as drift. It is
removed here, with a comment saying why it must not come back: pointing the
drift job at an uncreated path is now part of what the step asserts, so a
regression in the fix would show up as a failed scheduled run rather than
being masked.

(test.yml's mkdir -p "$RUNNER_TEMP/report" is left alone — it came from
#457's render step, not from this bug.)

Tests

Both written before the fix and watched fail against the old behaviour:

• CliTests.testNonexistentNestedOutputDirectoryIsCreated — renders to a
  nonexistent nested path, asserts exit 0 and that index.html is there.
  Before the fix: exit 1, no index.html.
• CliTests.testUnwritableOutputDirectoryFailsFastNamingThePath — a 0o555
  parent, asserts exit 64, that stderr names the path, and — the fail-fast
  half — that Building HTML never ran and that stderr no longer blames
  index.html. Before the fix: exit 1, all four assertions failed. Skipped
  when running as root, which ignores directory permissions.

Docs

README.md's exit-code section documented the old behaviour verbatim ("Exit 1
covers failures to write the output — for example -o pointing at a directory
that does not exist"). Corrected. The --output help text now says the
directory is created if missing.

Summary by CodeRabbit

• New Features
  • The HTML report command now automatically creates missing output directories, including nested paths.
• Bug Fixes
  • Invalid or unwritable output paths now fail quickly with exit code 64 and a path-specific diagnostic.
  • Output-writing failures continue to use exit code 1.
• Documentation
  • Updated command-line documentation to clarify output-directory creation and exit-code behavior.