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

Truncation + redaction of free-form text that flows into the version 2 JSON
document (warnings, compile-error messages, abort-detail messages, and
any other string field that captures user-code-derived bytes).

Contract: [`mutagen.json_schema`](https://github.com/iautom8things/mutagen_ex/blob/main/.spec/specs/json_schema.spec.md)
r10, r11.

Compiler diagnostics and exception messages can include credentials or
large excerpts from host code. This module redacts and bounds those
messages before the reporter serializes them.

## Truncation (r10)

Every sanitized binary is capped at `byte_size_limit/0` bytes
(default 4 KiB). When truncation occurs, the binary ends with the
literal marker `" ... <N bytes truncated>"` where `N` is the
byte-count that was dropped. Multibyte UTF-8 grapheme boundaries are
respected on a best-effort basis — we truncate on a codepoint
boundary rather than splitting a grapheme.

## Redaction (r11)

Built-in patterns redact URL userinfo, common credential keys, and
token prefixes. Add patterns via application config:

    config :mutagen_ex, redact: [~r/AWS_SECRET[A-Z0-9_]+=\S+/, "BEARER \S+"]

Each element of the list may be a `%Regex{}` or a binary regex
source. Matches are replaced with the literal string `[REDACTED]`.
Redaction runs BEFORE truncation so the replacement does not push
redacted bytes past the cap and then drop them as truncated text.

The default extra pattern list is empty.

## API

  * `clean/1` — full pass: redact then truncate. The standard entry
    point for all message and warning strings.
  * `clean/2` — same as `clean/1` but accepts an explicit opts list
    (`:byte_size_limit`, `:patterns`) for tests that need to override
    the default cap or pattern list without touching application env.
  * `truncate/2` — truncation only.
  * `apply_redactions/2` — redaction only.

# `apply_redactions`

```elixir
@spec apply_redactions(binary(), list()) :: binary()
```

Apply each pattern in `patterns` to `bin`, replacing every match
with `[REDACTED]`. Patterns may be `%Regex{}` or binary regex
sources. Binary sources are compiled with `Regex.compile!/1` on each
call; callers that care about performance should pre-compile.

An empty pattern list is a no-op.

# `byte_size_limit`

```elixir
@spec byte_size_limit() :: pos_integer()
```

Default byte-size limit. The cap is fixed at 4 KiB in v1. A future
version may make it configurable; until then, callers that need a
different cap pass `:byte_size_limit` to `clean/2` (test seam) or
`truncate/2` directly.

# `clean`

```elixir
@spec clean(binary() | nil | iodata()) :: binary() | nil
```

Apply built-in and configured redactions, then truncate to 4 KiB.
Returns the cleaned binary. Non-binary input is converted via
`to_string/1` first; `nil` is returned unchanged so callers can chain
with optional fields.

# `clean`

```elixir
@spec clean(
  binary() | nil | iodata(),
  keyword()
) :: binary() | nil
```

Same as `clean/1` but with explicit opts:

  * `:byte_size_limit` — pos_integer cap (default `byte_size_limit/0`)
  * `:patterns` — list of patterns (defaults to
    `Application.get_env(:mutagen_ex, :redact, [])`)

# `secret_key?`

# `truncate`

```elixir
@spec truncate(binary(), pos_integer()) :: binary()
```

Truncate `bin` to at most `limit` bytes. When truncation happens,
the returned binary ends with `" ... <N bytes truncated>"` and its
total `byte_size/1` may exceed `limit` by the length of the marker.
This is intentional: the marker is metadata about the truncation,
not part of the captured payload, and downstream consumers need a
visible signal that bytes were dropped.

Multibyte safety: we split on a codepoint boundary so we never emit
an invalid UTF-8 fragment. The marker bytes are pure ASCII.

---

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