# `MutagenEx.CLI`
[🔗](https://github.com/iautom8things/mutagen_ex/blob/v0.2.0/lib/mutagen_ex/cli.ex#L1)

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

# `error`

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

Structured error returned by `parse/1`.

# `reason`

```elixir
@type reason() :: MutagenEx.JsonReporter.abort_reason()
```

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

# `parse`

```elixir
@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 `t: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`).

---

*Consult [api-reference.md](api-reference.md) for complete listing*
