Immutable cache of {quoted_ast, source_text} tuples for the in-scope
source files of a mix mutagen run.
Contract: mutagen.coverage r6, r9.
Why both AST and verbatim source text
Two consumers need different shapes:
MutagenEx.MutationEnumeratorwalks the AST to find candidate sites.MutagenEx.JsonReporter(S6) renders abefore_sourcefield for each reported mutation.
Current contract (see mutagen.json_schema r4 + r12, post
mutagen-wrd.34): before_source is a verbatim source slice taken
by {line, column, end_line, end_column} against source_text
whenever the enumerator could derive end positions for the site
(the common case for AST 3-tuples). When end positions are
unavailable (bare-literal sites attributed to a parent operator,
some macro-expanded forms) the renderer falls back to aliasing
the Macro.to_string(original_ast) binary already computed for
before. The slice path uses byte indexing and never invokes
Macro.to_string/1, so the 2 * R rendering call-count cap
from r12 still holds.
Holding the verbatim source bytes the AST was parsed from keeps the slice deterministic: it is the byte content of the file at load time, not what's on disk now (which a concurrent edit could have changed).
Critical invariant (r6): source_text is byte-identical to
File.read!(file) at the moment load/1 was called. Each file is read
exactly once.
Categorised input (r9)
load/2 accepts an optional :categories opt whose value is a map
from category name (atom) to a list of file paths
(e.g. categories: %{scope: scope_files, test: test_files}). This is
input-only diagnostic metadata — the cache entry shape is unchanged
({Macro.t(), String.t()}); there is no per-entry category tag, no
3-tuple, no files_by_category/2 consumer API. Categorisation is logged
to telemetry-style diagnostics so observers can see "we loaded N scope
files + M test files" without changing how downstream phases look up
entries (they still call get(cache, file) by path).
The flat files arg remains the source of truth for what gets read;
category lists should be a partition of files (the implementation
does NOT enforce this — categorisation is advisory).
Immutability
The cache is a plain Map.t(). There is no put/3, no update/3. Once
load/1 returns, callers can only get/2. This is the runtime-level
enforcement of "the cache is immutable after the first build" (r6).
Summary
Types
An entry in the cache. AST is whatever Code.string_to_quoted/2 returns.
Reason atoms surfaced when a file cannot be loaded or parsed.
The cache itself: a map from relative file path to entry.
Functions
List the file keys in the cache. Order is not guaranteed.
Fetch the {ast, source} entry for file, or :error if absent.
Read and parse each file in files exactly once. Returns
{:ok, cache} on full success, or {:error, reason, details} on the
first file that fails to read or parse.
Types
An entry in the cache. AST is whatever Code.string_to_quoted/2 returns.
@type load_reason() :: :file_read_failed | :parse_error
Reason atoms surfaced when a file cannot be loaded or parsed.
The cache itself: a map from relative file path to entry.
Functions
List the file keys in the cache. Order is not guaranteed.
Fetch the {ast, source} entry for file, or :error if absent.
@spec load( [String.t()], keyword() ) :: {:ok, t()} | {:error, load_reason(), map()}
Read and parse each file in files exactly once. Returns
{:ok, cache} on full success, or {:error, reason, details} on the
first file that fails to read or parse.
Per r6, this is the only function that reads source files. The cache it returns is then handed unchanged to coverage, the mutation enumerator, and the mutation runner.
Opts
:reader—(file :: String.t() -> String.t()). Defaults to&File.read!/1. The seam exists so the C1/C2 spike findings aboutCode.compiler_options(debug_info: true)don't bleed into this module: the cache is purely about source bytes + parsed AST and is tested against in-memory strings without touching disk.:categories—%{atom() => [String.t()]}. Optional diagnostic partitioning of the flatfileslist (e.g.%{scope: [...], test: [...]}). Per r9 this is input-only: it does NOT change the cache entry shape, and there is no consumer API for looking up entries by category.