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 perdefmoduleblock in the file (r1). - Module name —
Module.Name(no/arity, no leading path). Resolves to a single record covering the matchingdefmoduleblock (r2). - MFA —
Module.Name.function/arity. Arity is required. Resolves to a single record whoseline_rangecovers only the matchingdef/defp/defmacro/defmacropclause(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 defs. 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. Perr7, 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 toPath.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
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).
Summary
Types
Injectable source loader. Receives a path, returns the file's bytes.
Atom-shaped reason for a resolution failure.
Functions
Resolve a single raw scope target to one or more %Scope{} records.
Types
Injectable source loader. Receives a path, returns the file's bytes.
@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.
@type result() :: {:ok, [MutagenEx.ScopeResolver.Scope.t()]} | {:error, reason(), map()}
Result of resolve/2.