@spec add(registry :: t(), paths :: [String.t()], today :: Date.t()) ::
  {t(), [String.t()], [String.t()]}

Adds paths to the registry, dated today.

Returns {registry, added, skipped}. Internal tests are skipped: they are covered by globs already, so listing them individually would only add churn. Entries are deduplicated and sorted, and the ratchet never removes anything.

@spec categorize(path :: String.t()) :: category()

The suite a test file belongs to, decided by its path.

Examples

iex> Mix.Statifier.RegressionRegistry.categorize("test/scion_tests/basic/basic0_test.exs")
:scion

iex> Mix.Statifier.RegressionRegistry.categorize("test/statifier/document_test.exs")
:internal

@spec conformance_categories() :: [category()]

The conformance suites, the only categories the ratchet grows by hand.

@spec corpus_files(category :: category(), root :: String.t()) :: [String.t()]

Every test file on disk for a conformance category, sorted.

Used by mix test.baseline to find candidates the registry does not know about yet. root prefixes the suite directory; it defaults to the project root and exists so the tasks can be pointed at a fixture tree under test.

@spec corpus_stats(
  passing :: [String.t()],
  category :: category(),
  root :: String.t()
) :: stats()

How much of category's emitted corpus passing covers.

total counts the test files on disk under the suite directory, which is the only denominator the ratchet can reach 100% of - cases excluded at generation time (tools/corpus/*/exclusions.exs) never emit a file. The numerator is the intersection of passing with those files, never a plain length, because a registry entry may be a glob or may name a path outside the suite directory. percent is nil when the corpus is empty, so callers report "no files" rather than dividing by zero.

@spec default_path() :: String.t()

Path of the registry file, relative to the project root.

@spec encode(registry :: t()) :: String.t()

Encodes registry as JSON with sorted keys, two-space indent, and one array entry per line, so that ratcheting in a test is a minimal diff.

Examples

iex> Mix.Statifier.RegressionRegistry.encode(%{"scion_tests" => ["a.exs"], "n" => 1})
~s|{\n  "n": 1,\n  "scion_tests": [\n    "a.exs"\n  ]\n}\n|

@spec expand(registry :: t(), category :: category()) :: {[String.t()], [String.t()]}

Expands the patterns held under category into test files.

Returns {files, missing}, where missing lists entries that matched nothing on disk. A registry entry that no longer exists is a hole in the ratchet, so callers report it rather than skipping it.

@spec expand_patterns(patterns :: [String.t()]) :: {[String.t()], [String.t()]}

Expands a list of literal paths and globs into existing test files.

Returns {sorted_unique_files, patterns_that_matched_nothing}.

Examples

iex> Mix.Statifier.RegressionRegistry.expand_patterns(["test/no_such_test.exs"])
{[], ["test/no_such_test.exs"]}

@spec files(registry :: t()) :: {[String.t()], [String.t()]}

Every test file the registry expands to, across all categories.

Returns {files, missing} with the same meaning as expand/2.

@spec key(category :: category()) :: String.t()

The registry key holding category.

Examples

iex> Mix.Statifier.RegressionRegistry.key(:scion)
"scion_tests"

@spec load(path :: String.t()) :: {:ok, t()} | {:error, String.t()}

Loads the registry from path.

Returns {:error, reason} rather than raising: both tasks report the reason and exit non-zero, and a malformed registry must never be mistaken for an empty one.

@spec save(registry :: t(), path :: String.t()) :: :ok | {:error, String.t()}

Writes registry back to path, pretty-printed.

@spec stats_lines(
  passing :: [String.t()],
  categories :: [category()],
  root :: String.t()
) :: [
  String.t()
]

One report line per conformance category, plus the denominator caveat.

Each per-category line reads " LABEL: passing/total (percent%)", with labels padded so the counts line up. A category whose total is 0 is omitted entirely. Callers prefix these lines with their own header (the numerator's meaning differs between a scan and a ratchet run, so the header text is not this function's job) and print the block as-is otherwise. Returns [] - no lines, no caveat - when no category has any emitted files, so a fixture tree with no corpus prints nothing at all.

@spec suite_dir(category :: category()) :: String.t() | nil

Directory holding the corpus for a conformance category.

Examples

iex> Mix.Statifier.RegressionRegistry.suite_dir(:w3c)
"test/scxml_tests"

@spec suite_label(category :: category()) :: String.t() | nil

Human-readable name of a conformance suite.

Examples

iex> Mix.Statifier.RegressionRegistry.suite_label(:scion)
"SCION"

iex> Mix.Statifier.RegressionRegistry.suite_label(:internal)
nil

@spec test_args(paths :: [String.t()]) :: [String.t()]

mix test arguments that make paths runnable.

Conformance suites are excluded by default, so their tag has to be included explicitly.

Examples

iex> Mix.Statifier.RegressionRegistry.test_args(["test/scion_tests/basic/basic0_test.exs"])
["--include", "scion"]