MutagenEx.AstCache (mutagen_ex v0.2.0)

Copy Markdown View Source

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:

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.

t()

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

entry()

@type entry() :: {Macro.t(), String.t()}

An entry in the cache. AST is whatever Code.string_to_quoted/2 returns.

load_reason()

@type load_reason() :: :file_read_failed | :parse_error

Reason atoms surfaced when a file cannot be loaded or parsed.

t()

@type t() :: %{optional(String.t()) => entry()}

The cache itself: a map from relative file path to entry.

Functions

files(cache)

@spec files(t()) :: [String.t()]

List the file keys in the cache. Order is not guaranteed.

get(cache, file)

@spec get(t(), String.t()) :: {:ok, entry()} | :error

Fetch the {ast, source} entry for file, or :error if absent.

load(files, opts \\ [])

@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 about Code.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 flat files list (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.