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

Canonicalisation and safety checks for `--json <path>`.

`mix mutagen` accepts arbitrary user-supplied output paths via `--json`.
Combined with the in-process compile-and-execute pipeline
(`mutagen.decision.in_process_pipeline`), an un-validated path is an
arbitrary-file-write primitive: a malicious mutated test in a third-party
library could redirect the report into `/etc/`, `~/.ssh/authorized_keys`,
or any other path the OS user can write.

This module is the single home for the path-safety contract. Two layers:

  1. `validate_literal/1` — pure-string checks. Runs at CLI parse time so
     the bad shapes (NUL byte, `..` segments) produce an `:unsafe_json_path`
     abort-JSON before any filesystem touch.
  2. `canonicalize/2` — filesystem-aware check. Runs once after CLI parse
     but before any mutation phase. Expands the path, follows symlinks, and
     refuses any path whose resolved target lives outside the project root
     (unless the caller passed `unsafe_outside_project: true`).

The split keeps `MutagenEx.CLI` pure (no IO from the parser) while letting
the mix task gate the run on the FS-level check before any mutation runs.

## Project root

The project root is `File.cwd!/0` at the time of invocation — `mix mutagen`
always runs from the host project's root (Mix enforces this), so cwd is a
reliable anchor. Symlinks in the cwd itself are resolved once via
`Path.expand/1` so a symlinked project directory does not spuriously
trip the inside-root check.

# `details`

```elixir
@type details() :: %{
  :variant =&gt; :nul_byte | :traversal | :outside_project_root | :empty_path,
  :path =&gt; String.t(),
  :message =&gt; String.t(),
  optional(:resolved) =&gt; String.t(),
  optional(:project_root) =&gt; String.t()
}
```

Details map shape attached to every rejection.

# `reason`

```elixir
@type reason() :: :unsafe_json_path
```

Reason atom returned on rejection. Single value; details map carries the variant.

# `canonicalize`

```elixir
@spec canonicalize(
  String.t(),
  keyword()
) :: {:ok, String.t()} | {:error, reason(), details()}
```

Filesystem-level canonicalisation.

Returns `{:ok, absolute_path}` for the resolved destination. Existing
symlinks are resolved. The report file or its parent can be missing.
The writer rechecks the destination before creating or replacing it.

Rejects `{:error, :unsafe_json_path, details}` when:

  * Any existing component is a symlink whose target escapes the project
    root (`:outside_project_root`).
  * The fully-resolved absolute path is outside the project root and the
    caller did not pass `unsafe_outside_project: true` (`:outside_project_root`).

Options:

  * `:project_root` — absolute path of the project root. Defaults to
    `File.cwd!/0`. Resolved through `Path.expand/1` so a symlinked cwd
    does not trip the inside-root check.
  * `:unsafe_outside_project` — boolean. When `true`, the inside-root
    check is bypassed; only the symlink-escape check runs. Default `false`.

Note: this function does NOT call `validate_literal/1` — callers (the
CLI) run that at parse time, well before this function. Calling
`canonicalize/2` with a literal-unsafe path is a programmer error, but
to be safe the function still re-runs the cheap NUL-byte check (Erlang
IO operations on NUL-containing paths raise; we prefer a typed error).

# `validate_literal`

```elixir
@spec validate_literal(String.t()) :: :ok | {:error, reason(), details()}
```

Pure-string validation of a `--json` path literal.

Rejects:

  * NUL bytes anywhere in the path (`:nul_byte`).
  * Any `..` segment in the path (`:traversal`). A literal `..` is the only
    way to escape upward without involving the filesystem; refusing it at
    the literal layer means downstream resolution does not need to deal
    with it.
  * Empty strings (`:empty_path`). `--json` requires a non-empty value.

Accepts everything else, including:

  * Relative paths (resolved against cwd at write time).
  * Absolute paths (anchored where they are — the inside-root check happens
    in `canonicalize/2`).
  * Paths that pass through symlinks (handled in `canonicalize/2`).

Returns `:ok` or `{:error, :unsafe_json_path, details}`.

---

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