MutagenEx.CLI (mutagen_ex v0.2.0)

Copy Markdown View Source

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 --since or --site.
  • --tests <target> selects tests, repeatable up to 100 times. Use auto on its own. It is the default with --since or --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-project to 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-escalate is 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-project is passed).
  • --unsafe-json-outside-project — boolean, default false. Opt-in to writing the --json output 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_sites before any mutation phase runs (per mutagen.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 carries truncated: true (per mutagen.cli.r13).
  • --max-concurrency <int> — positive integer, default 1 (fully-serial, matches v1.0 semantics exactly). The mutation loop dispatches per-site tasks via Task.Supervisor.async_stream_nolink/4; results are collected in input order so the JSON document remains byte-identical across --max-concurrency values on deterministic scopes. Set to N > 1 to opt in to parallelism; only safe for callers with collision-free input (no two sites mutating the same module, no shared :cover instrumentation state). See mutagen.mutation_pipeline.r15 for 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 (stdout by 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/0 reports :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 per mutagen.decision.no_pretty_output_v1.
  • Self-mutation scope targets — any raw --scope target whose module-name shape begins with MutagenEx. or equals exactly Mix.Tasks.Mutagen is refused at parse time per mutagen.decision.self_mutation_refused. This is a defence-in-depth heuristic; full resolution-based refusal lives in MutagenEx.ScopeResolver (S3a) and ultimately at pipeline entry (S6).
  • --tests tag:NAME where NAME falls 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 though MutagenEx.TestSelector uses 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: --tests targets (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

Structured error returned by parse/1.

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

error()

@type error() :: {:error, reason(), map()}

Structured error returned by parse/1.

reason()

Atom-shaped reason for a parse failure (see mutagen.json_schema.abort_reason).

Functions

parse(argv)

@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).