MutagenEx.ScopeResolver (mutagen_ex v0.2.0)

Copy Markdown View Source

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

Result of resolve/2.

Functions

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

Types

loader()

@type loader() :: (String.t() -> String.t())

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

reason()

@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()

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

Result of resolve/2.

Functions

resolve(target, opts \\ [])

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