Pure command-line argument parser for mix mutagen.
Built on OptionParser with no third-party dependency, per
mutagen.cli Out of Scope (intent).
Contract
parse/1 is total: every input shape returns either
{:ok, %MutagenEx.Config{}} or {:error, reason, details} where reason
is an atom matching the JSON schema's abort_reason vocabulary. The Mix
task (Mix.Tasks.Mutagen) is responsible for handing the error tuple to
the reporter and choosing an exit code; this module never calls IO,
System.halt/1, or File.write!/2.
This split is the seam the ticket's "private dispatch table" exploits: the Mix task's reporter can be swapped in tests, but the parser is pure enough to be tested directly without any injection.
Recognised flags
--scope <target>selects one scope, repeatable up to 100 times. Required unless you use--sinceor--site.--tests <target>selects tests, repeatable up to 100 times. Useautoon its own. It is the default with--sinceor--site.--since <ref>plans changed runtime sites from the merge base.--site <id>selects one site by report ID or opaque reference.--summary <path>writes Markdown within the project root, as with--json. Use--unsafe-json-outside-projectto allow a path outside it.--summary-max <int>caps the individual findings. Defaults to five.--escalate— widen automatic test selection after the narrow pass.--no-escalateis accepted with no effect for one release.--escalate-max-files <int>— non-negative cap per step, default 20.--escalate-budget-ms <int>— total time for the extra passes, default 120000. Single-site runs cap it at the larger of 30 seconds and ten times the narrow baseline duration. Use 0 to remove the escalation time limit.--timeout-ms <int>— positive per-mutant deadline override.--seed <int>— non-negative integer, default 0.--json <path>— optional file path; when omitted, the final document is written to stdout. The path is validated at parse time (NUL bytes and..segments are refused) and canonicalised at write time (symlinks resolved; the resolved path must stay inside the project root unless--unsafe-json-outside-projectis passed).--unsafe-json-outside-project— boolean, default false. Opt-in to writing the--jsonoutput outside the project root. CI integrations that target an artifacts directory above the project root pass this flag explicitly; everyday use should leave it off.--max-sites <int>— positive integer, default 10_000. Upper bound on enumerated mutation sites for one run. Exceeding it aborts with:too_many_sitesbefore any mutation phase runs (permutagen.mutation_enumeration.r7).--budget-ms <int>— optional positive integer. Aggregate wall-clock budget for the mutation phase in milliseconds. When exceeded the runner terminates gracefully and the JSON document carriestruncated: true(permutagen.cli.r13).--max-concurrency <int>— positive integer, default1(fully-serial, matches v1.0 semantics exactly). The mutation loop dispatches per-site tasks viaTask.Supervisor.async_stream_nolink/4; results are collected in input order so the JSON document remains byte-identical across--max-concurrencyvalues on deterministic scopes. Set toN > 1to opt in to parallelism; only safe for callers with collision-free input (no two sites mutating the same module, no shared:coverinstrumentation state). Seemutagen.mutation_pipeline.r15for the in-process pipeline caveat that motivates default-1.--stream— boolean, default false. When set, the runner emits one NDJSON line per completed site (and one envelope line on start and finish) to the configured output (stdoutby default, or--json <path>). The final aggregate JSON document is still emitted on the same sink as the last line. Consumers tee on\n.--no-progress— boolean, default false. When set, the human- readable progress bar / counter is never written to stderr. Default behaviour is to emit progress only when stderr is a TTY (:io.getopts/0reports:terminal).--no-host-app— skips starting the host OTP application.--no-test-alias— skips host test alias pre-steps.--boot-timeout-ms <int>— positive startup deadline, default 300000.
Refused flags
--no-json— refused permutagen.decision.no_pretty_output_v1.- Self-mutation scope targets — any raw
--scopetarget whose module-name shape begins withMutagenEx.or equals exactlyMix.Tasks.Mutagenis refused at parse time permutagen.decision.self_mutation_refused. This is a defence-in-depth heuristic; full resolution-based refusal lives inMutagenEx.ScopeResolver(S3a) and ultimately at pipeline entry (S6). --tests tag:NAMEwhereNAMEfalls outside the charset~r/A[a-z][a-z_0-9]{0,63}z/. This is the front-door bound on the atom-table-DOS risk (mutagen.cli.r11, mutagen-wrd.20): even thoughMutagenEx.TestSelectoruses string comparison and never materializes an atom from the user-supplied tag name, the charset gate keeps adversarial inputs (tag:$(uuidgen)-style loops) from reaching the selector at all. Non-tag:--teststargets (file paths, file:line) are not gated by this rule — they don't feed atom resolution.
Caps
Per mutagen.cli.r12, --scope and --tests accept at most 100
occurrences each. Excess is refused with :too_many_targets. The cap
is structural: it is enforced before any filesystem touch (scope or
test target resolution).
Summary
Types
Atom-shaped reason for a parse failure (see mutagen.json_schema.abort_reason).
Functions
Parse a list of raw CLI argv tokens into a %MutagenEx.Config{} or a
structured error.
Types
Structured error returned by parse/1.
@type reason() :: MutagenEx.JsonReporter.abort_reason()
Atom-shaped reason for a parse failure (see mutagen.json_schema.abort_reason).
Functions
@spec parse([String.t()]) :: {:ok, MutagenEx.Config.t()} | error()
Parse a list of raw CLI argv tokens into a %MutagenEx.Config{} or a
structured error.
Argv is what Mix.Task.run/1 hands the task: every token after mix mutagen as a separate string.
Returns {:ok, %Config{}} for valid input.
Returns {:error, reason, details} for any failure. reason is one atom
from reason/0; details is a map with at least a :message string and
any reason-specific fields (e.g. :flag for :unknown_flag, :value for
:invalid_timeout).