--json emits ParsedResult behind a documented wire contract + 4.0 release notes (#391, Tasks 14–15) - #451

Tasks 14 and 15 of the migration plan for #391 — the last phase-5 PR. --json stops dumping xcresulttool's legacy object graph and emits the ParsedResult model behind a documented, versioned wire contract; the 4.0 release notes are drafted in-repo.

Task 14 — --json emits our own schema

The contract came first: docs/json-schema.md documents field names and nesting with the complete worked example from a real SanityResults render, the five status spellings, one uniform null rule (every key always present, absent values are explicit null, arrays never null), duration units and the timestamp format, array ordering guarantees, the two permitted cross-backend value-difference classes, and a semver schemaVersion policy with consumer guidance.

The encoder is an explicit layer, not a synthesized Encodable (Classes/Models/JsonReport.swift): every wire key is an explicit string, so renaming a Parsed* property breaks compilation instead of silently renaming public output — the spec's stated reason. ParsedStatus keeps no raw values; the encoder owns the five wire spellings in a switch. The plan's Task 14 snippet (synthesized conformance + raw values) is superseded; amendment recorded in the plan. Summary retains the parsed runs, so --json needs no second parse. ResultFile.exportJson() — the last exportRecursiveJson() call, kept alive since Task 5a — is deleted; XCResultKit is now confined to ResultReading/Legacy/ (two files, deleted together in phase 6).

Cross-backend discipline, tested (JsonReportTests, differential-style, both backends, all three fixtures):

• Schema identity: key-path sets compared after collapsing the tree's recursion edges — wrapperGroups means legacy alone places group nodes at nested positions, so raw path sets differ for a permitted class-1 reason; the collapsed comparison still fails on any key one backend's groups or test cases carry and the other's lack.
• Value identity outside the two classes: a JSON-level masker (JsonClassMask, the wire counterpart of KnownLossMasker) removes exactly the four declared class-1 losses, with non-vacuity stats so a mask that stops masking fails the test. What remains must be deeply equal — and is, on all three fixtures.
• Class 2, never blind equality: legacy arguments asserted == [] explicitly; modern asserted non-empty (["1","2","3"]) for SwiftTestingSuite/parameterizedAddition(value:), so the assertion cannot pass vacuously now that the parameterized fixture exists.
• Contract pins: status spellings and the …Z millisecond timestamp shape asserted against real output.

One reader-parity gap surfaced and fixed — exactly what the --json differential exists to catch: under a retry-enabled plan, legacy stamps every test summary with repetitionPolicySummary ("iteration 1" of a policy that never fired) while modern emits Repetition children only for real repetitions. Nothing renders a lone iteration number (the HTML differential is structurally blind to it), but --json emits the model, so it showed up as legacy 1 vs modern null on every single-run test in RetryResults. LegacyResultReader.strippingLoneIterationNumber makes a single execution carry no repetition information on either backend; pinned in LegacyResultReaderTests, recorded as a Task 14 execution rule in the spec.

Task 15 — documentation and release notes

• docs/release-notes/4.0.0.md — drafted in the 3.0.0 release's narrative style for the release to source. Covers the full checklist: the --json break with the contract linked and the break-once framing; --result-reader; content-addressed attachment export names (<payloadId>.<ext>, fixes Modern render of regenerated RetryResults faults with payloadExportFailed on a screen-recording attachment (Xcode 26.2) #449) with the on-disk-only caveat; digest-derived run-log names; parameterized legacy rendering collapsing to one case; skip reasons now appearing; failure rows rendering where the assertion fired, including that JUnit inherits the reposition (shape 4); activity types and per-activity durations leaving the report; the four declared reader differences; and the deliberate phase-6 deferral.
• README — --result-reader section, the --json break with a before/after snippet, and the known backend differences drawn from the allow-list.
• Spec — status header marking phases 1–5 landed (The port: ParsedResult model, LegacyResultReader, and the renderer migration (#391, Tasks 3–5b) #443, ModernResultReader, ModernPayloadStore, and extension-based attachment typing (#391, Tasks 8–10) #447, Backend selection and the --result-reader flag (#391, Task 11) #448, THE DIFFERENTIAL: legacy/modern parity held to the declared allow-list + forced-modern CI leg (#391, Tasks 12–13) #450, this PR), phase 6 deferred until Apple removes the legacy commands; new "Task 14 execution rules" section.

Carried findings (all folded in, none deferred)

1. R2 keep-guard test (THE DIFFERENTIAL: legacy/modern parity held to the declared allow-list + forced-modern CI leg (#391, Tasks 12–13) #450 review): testNoStartRowsWithContentSurviveTheAnnotationDrop pins all three branches of the guard at ModernResultReader.parseActivity on a crafted document — a no-startTime row with an attachment, with a failure flag, or with surviving children is kept; the contentless one drops.
2. test.yml artifact collision (THE DIFFERENTIAL: legacy/modern parity held to the declared allow-list + forced-modern CI leg (#391, Tasks 12–13) #450 review): failure-artifact name is now suffixed per matrix leg (xcresult-fixtures-${{ matrix.result_reader }}); upload-artifact v4 refuses duplicate names, so a both-legs-fail run would have lost the second upload.
3. ModernResultReader, ModernPayloadStore, and extension-based attachment typing (#391, Tasks 8–10) #447 review items, all three:
   • ModernPayloadStore now takes XCResultToolInvoking (the existing seam) instead of the concrete client; testFailedExportRecordsAFaultAndLeaksNoTempDirectory proves export-failure faulting in-suite.
   • The failed one-shot export no longer leaks its temp directory (removed in the catch; same test asserts no survivor).
   • An out-of-range repetition index no longer falls back silently to runs.first: it renders no activities for that iteration, records .missingActivities, and testOutOfRangeRepetitionIndexDegradesLoudly pins that repetition 1's rows are not borrowed.

Verification

• swiftformat --lint clean, swiftlint non-strict clean apart from one type-length warning on a test class (matching the existing ModernResultReaderTests precedent), shellcheck clean, release build clean.
• Full suite green on both reader legs (swift test and XCHR_RESULT_READER=modern swift test) against freshly generated fixtures.

Refs #391. Milestone 4.0. Do not merge without review.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added a versioned, backend-neutral JSON report format with runs, tests, activities, attachments, statuses, and timestamps.
  • Added --result-reader auto|legacy|modern and XCHR_RESULT_READER configuration.
  • Modern reader output now includes test-case arguments where available.

• Bug Fixes

  • Improved handling of repeated tests, missing activities, failed attachments, and activity metadata.
  • Prevented collisions in parallel test artifacts.

• Documentation

  • Added comprehensive JSON schema documentation and updated migration and 4.0.0 release notes.