MutagenEx.JsonReporter (mutagen_ex v0.2.0)

Copy Markdown View Source

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

abort_reason()

@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

emit_error(report, abort_reason)

@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(report)

@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(value)

render_host_names(kind, paths, include_host_output?)

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.