Single owner of the version 2 JSON output document for mix mutagen.
Contract: mutagen.json_schema
r1-r9. Decision: mutagen.decision.json_reporter_owns_error.
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.
Summary
Types
Atom-shaped reason for any non-zero exit. Matches the vocabulary in
mutagen.json_schema.r5.
Functions
Emit the abort-shape JSON document.
Emit the success-shape JSON document.
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.
Types
@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.
Functions
@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.
@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.
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.