# `MutagenEx.JsonReporter`
[🔗](https://github.com/iautom8things/mutagen_ex/blob/v0.2.0/lib/mutagen_ex/json_reporter.ex#L315)

Single owner of the version 2 JSON output document for `mix mutagen`.

Contract: [`mutagen.json_schema`](https://github.com/iautom8things/mutagen_ex/blob/main/.spec/specs/json_schema.spec.md)
r1-r9. Decision: [`mutagen.decision.json_reporter_owns_error`](https://github.com/iautom8things/mutagen_ex/blob/main/.spec/decisions/json_reporter_owns_error.md).

Both success and abort variants emit a document of the same schema family.
The difference between the two is whether `aborted` is `false` or `true`
and which sub-blocks are populated. There is no separate `ErrorReporter`
module.

## API

  * `emit_report(report)` — full pipeline result. Returns `{iodata, 0}`.
  * `emit_error(report, abort_reason)` — abort variant. Returns
    `{iodata, 2}`.

Per `mutagen.json_schema.r6`, neither function performs I/O. They return
iodata so the calling Mix task can choose between `IO.write/1` and
`File.write!/2` based on `Config.json_path`.

The encoded document terminates with exactly one trailing newline (`r8`).

## Report struct

`%Report{}` is the in-memory shape the pipeline assembles. Field-by-field
it mirrors the schema (`r2`); fields the pipeline never populated are
`nil` rather than missing (`r5`).

## JSON encoding

Encoding uses Erlang/OTP 27+'s `:json` module — no third-party
dependency, per `.spec/AGENTS.md`'s deps discipline. The custom encoder
function maps `nil` to `null` (the default `:json` encoder refuses
`nil`) and forwards every other value to `:json.encode_value/2`.

Map keys come out alphabetically sorted by `:json.encode_map/2`, which
is what we want — the schema documents top-level keys but the golden
fixture comparison is byte-exact, so any non-deterministic ordering
would break `r9`.

# `abort_reason`

```elixir
@type abort_reason() ::
  :unsupported_elixir_version
  | :unrecoverable_restore_failure
  | :baseline_timeout
  | :test_helper_load_failed
  | :no_tests_run
  | :umbrella_root
  | :missing_tests
  | :invalid_redact_config
  | :summary_write_failed
  | :diff_unavailable
  | :invalid_target
  | :cover_module_unavailable
  | :test_alias_failed
  | :baseline_red
  | :cover_compile_failed
  | :invalid_site
  | :invalid_seed
  | :invalid_max_concurrency
  | :host_app_start_failed
  | :escalation_crashed
  | :unsafe_summary_path
  | :invalid_boot_timeout
  | :parse_error
  | :site_not_found
  | :invalid_summary_max
  | :file_not_found
  | :too_many_sites
  | :self_mutation_refused
  | :invalid_since_ref
  | :module_beam_missing
  | :module_not_found
  | :invalid_line
  | :invalid_max_sites
  | :host_setup_timeout
  | :missing_scope
  | :unrecognised_target
  | :invalid_budget_ms
  | :invalid_mix_env
  | :arity_required
  | :ex_unit_run_failed
  | :no_tests_match
  | :host_loadpaths_failed
  | :function_not_found
  | :too_many_targets
  | :invalid_timeout
  | :runtime_load_failed
  | :flag_not_supported_in_v1
  | :unsupported_otp_version
  | :unknown_flag
  | :colon_syntax_unsupported
  | :host_compile_failed
  | :summary_path_conflict
  | :coverage_timeout
  | :file_read_failed
  | :invalid_input
  | :test_file_load_failed
  | :unsafe_json_path
  | :cover_already_running
  | :invalid_tag_name
```

Atom-shaped reason for any non-zero exit. Matches the vocabulary in
`mutagen.json_schema.r5`.

# `emit_error`

```elixir
@spec emit_error(MutagenEx.JsonReporter.Report.t(), abort_reason()) :: {iodata(), 2}
```

Emit the abort-shape JSON document.

The `abort_reason` argument is normalised onto the report (overriding any
prior value) so callers can build the report incrementally and let the
reporter pick the exit code at the moment of emission.

Exit code is `2` for all abort reasons in v1. The schema does not
differentiate exit codes by reason (the JSON's `abort_reason` field
carries that signal); we use `2` to distinguish from the conventional
`1` ExUnit failure exit and from `0` success.

# `emit_report`

```elixir
@spec emit_report(MutagenEx.JsonReporter.Report.t()) :: {iodata(), 0}
```

Emit the success-shape JSON document.

`report.aborted` MUST be `false`; this function will still succeed if
given an aborted report but the caller should be using `emit_error/2` in
that case. The exit code is always `0`.

# `filter_to_wire`

# `render_host_names`

Renders host-derived names under a fixed warning kind. Use only a
tool-owned kind. Runner warnings can also carry `{:host_names, kind, names}`
to apply this policy at the JSON boundary.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
