MutagenEx.JsonStreamer (mutagen_ex v0.2.0)

Copy Markdown View Source

Per-site NDJSON line emitter for mix mutagen --stream.

Contract: mutagen.json_schema r14 (NDJSON line shape, byte-equal to the equivalent entry in the final aggregate document's mutation.results / mutation.compile_errors).

Each line is a JSON object terminated by a single \n. The wire shape mirrors what MutagenEx.JsonReporter emits inside the final document — that is, the same map keys and value encodings, plus a kind discriminator ("result" or "compile_error") and the same version literal the aggregate uses. Consumers parsing line-by-line can route on kind:

{"version":"2","kind":"start","total":42,"meta":{...}}
{"version":"2","kind":"result","id":"...","status":"killed","confidence":"high",...}
{"version":"2","kind":"compile_error","id":"...","message":"..."}
{"version":"2","kind":"end","meta":{"id_scheme":"2",...},"aborted":false,"abort_reason":null,
 "kill_rate":0.81,...}

start and end envelope lines bracket the run. Per-site result and compile_error lines are emitted in input order — the runner streams them through :on_site_completed AS the per-input-index task completes (via the async_stream's ordered collection guarantee), which means the byte-identical-output gate holds for the concatenated stream lines too. The Mix task writes the aggregate document after the stream and it carries no kind.

Summary

Types

I/O sink. Any iolist-accepting function or a device.

Functions

Emit a per-site compile_error line.

Emit the end envelope line.

Emit a per-site result line (status ∈ killed/survived/timeout/error).

Emit the start envelope line. Returns :ok.

Types

sink()

@type sink() :: (iodata() -> any()) | IO.device()

I/O sink. Any iolist-accepting function or a device.

Functions

emit_compile_error(sink, entry, options \\ %Report{})

Emit a per-site compile_error line.

emit_end(sink, report)

@spec emit_end(sink(), MutagenEx.JsonReporter.Report.t()) :: :ok

Emit the end envelope line.

report is the final %Report{} the pipeline assembled. The line carries report metadata, including the ID scheme, and the counters (total, killed, survived, timeout, compile_error, kill_rate) AND the abort fields, so a consumer that only saw the stream can produce the same top-level summary without parsing the full aggregate document.

emit_result(sink, result_map, options \\ %Report{})

Emit a per-site result line (status ∈ killed/survived/timeout/error).

Accepts a rendered result or the raw result from the runner.

emit_start(sink, total, meta)

@spec emit_start(sink(), pos_integer() | non_neg_integer(), map()) :: :ok

Emit the start envelope line. Returns :ok.

total is the total site count the runner will attempt; meta is the same meta block the final document carries (tool version, Elixir/OTP version, ExUnit seed, and fail-fast setting), without timings or final completeness.