# `MutagenEx.ScopeResolver`
[🔗](https://github.com/iautom8things/mutagen_ex/blob/v0.2.0/lib/mutagen_ex/scope_resolver.ex#L19)

Resolves user-supplied `--scope` targets into concrete
`%MutagenEx.ScopeResolver.Scope{}` records describing the file, line range,
and module each target points at.

This module implements the behavioural contract in
`.spec/specs/scope_resolution.spec.md` (`mutagen.scope_resolution`).

## Target shapes

Per `mutagen.decision.scope_syntax_simplified`, exactly three shapes are
accepted:

  * **File path** — anything ending in `.ex` (e.g. `lib/foo.ex`). Resolves
    to one record per `defmodule` block in the file (`r1`).
  * **Module name** — `Module.Name` (no `/arity`, no leading path). Resolves
    to a single record covering the matching `defmodule` block (`r2`).
  * **MFA** — `Module.Name.function/arity`. Arity is required. Resolves to
    a single record whose `line_range` covers only the matching
    `def`/`defp`/`defmacro`/`defmacrop` clause(s) for that arity (`r3`).

Targets containing a `:` are rejected with
`reason: :colon_syntax_unsupported` (`r4`). Module-shaped targets with a
lowercase trailing segment but no `/arity` are rejected with
`reason: :arity_required` (`r3`).

Resolution is purely an AST walk: source files are read via the injectable
loader (default `&File.read!/1`) and parsed with
`Code.string_to_quoted/2` requesting line/column metadata. No compile is
ever invoked; no file on disk is modified (`r6`).

## Atom safety (`r8`, mutagen-wrd.20)

Module-shaped and MFA-shaped targets carry user-controlled strings (e.g.
`Foo.Bar`, `Foo.bar/1`). The resolver does NOT call `String.to_atom/1` on
any segment of these targets. Module matching against the source's
`defmodule` blocks is performed via string comparison: the user's
canonical form (e.g. `"Elixir.Foo.Bar"`) is compared against
`Atom.to_string/1` of each AST-derived `defmodule` atom. The matched atom
populates `%Scope{module: ...}` so downstream code keeps an atom-typed
identifier — but that atom comes from the AST (legitimate; created during
the parse of source files on disk), never from the user's input.

Function-name segments use `String.to_existing_atom/1`: the function-name
atom (`bar` in `Foo.bar/1`) is compared against atoms produced by parsing
source `def`s. If the function name is not a registered atom anywhere,
`String.to_existing_atom/1` raises `ArgumentError`, which the resolver
converts to `:function_not_found`. This keeps the atom table bounded by
the project's source corpus, not by the cardinality of attacker input.

## Opts

  * `:loader` — `(file :: String.t() -> String.t())`. Default
    `&File.read!/1`. Per `r7`, this is the seam that lets tests work over
    synthetic source strings without touching disk.
  * `:source_files` — `[String.t()]`. For module-name and MFA targets, the
    list of project files to search. Defaults to
    `Path.wildcard("lib/**/*.ex")` so production callers don't have to
    build the list themselves. Tests pass an explicit list of synthetic
    paths so resolution stays deterministic.

## Returns

`{:ok, [%Scope{}, ...]}` on success (always exactly one record for
module/MFA targets; one or more for file targets).

`{:error, reason, details}` for any failure. `reason` is one atom from
`t:reason/0`; `details` is a map with at least `:target` (the raw user
string) and a human-readable `:message`. Reason-specific fields may also
be present (e.g. `:file` for `:file_not_found`).

# `loader`

```elixir
@type loader() :: (String.t() -&gt; String.t())
```

Injectable source loader. Receives a path, returns the file's bytes.

# `reason`

```elixir
@type reason() ::
  :colon_syntax_unsupported
  | :arity_required
  | :module_not_found
  | :function_not_found
  | :file_not_found
  | :file_read_failed
  | :parse_error
  | :unrecognised_target
```

Atom-shaped reason for a resolution failure.

# `result`

```elixir
@type result() ::
  {:ok, [MutagenEx.ScopeResolver.Scope.t()]} | {:error, reason(), map()}
```

Result of `resolve/2`.

# `resolve`

```elixir
@spec resolve(
  String.t(),
  keyword()
) :: result()
```

Resolve a single raw scope target to one or more `%Scope{}` records.

See the module doc for opts and result shape.

---

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