StatifierBlocks.Runtime.FixtureRuns (StatifierBlocks v0.26.0)

Copy Markdown View Source

Turns (document, palette, fixtures) into a list of per-row verdicts, by compiling the document once and driving the compiled chart once per fixture row (sb-4yze, Phase 1).

Namespace: StatifierBlocks.Runtime.*, not StatifierBlocks.Fixtures.*

This module runs a chart at session time - Statifier.compile/2 plus one Statifier.initialize/2 per row - rather than authoring anything, and lib/statifier_blocks/runtime/subchart.ex's moduledoc already set the precedent for what that half of the package is called: StatifierBlocks.Runtime.* reads as "the half that runs", set against the authoring half that is everything else in lib/.

Unguarded, on purpose

Every LiveView module in this package sits behind an Code.ensure_loaded?(...) presence check on the LiveView library itself (ADR-0005 decision 1). This module carries no such guard and names no LiveView module, because it is not a LiveView concern - it is a pure function of a document, a palette and a fixtures source, and StatifierBlocks.Shell's own moduledoc states the rule this follows: "what is worth testing goes in lib/statifier_blocks/, unguarded." The headless suite (the one CI job proves compiles and passes with that library entirely absent) exercises this module directly.

Why this calls Statifier.compile/2 and Statifier.initialize/2 directly

Statifier.Testing.Case is the ExUnit case template that names the four-function driving surface (compile/2, initialize/2, send_event/2, active_leaf_states/1 - ADR-0053, ADR-0006). It is use-able only from a test, and its own moduledoc forbids any module under lib/ outside Statifier.Testing.* from referencing anything inside it. So this module calls the four functions on Statifier itself - that direct call is the ADR-0053 surface, not a way around it - and the test suite below is free to use Statifier.Testing.Case where that helps.

:declare is the host's raw list, never host_roots

opts[:declare] is forwarded verbatim to StatifierBlocks.Compiler.compile/3 as its own :declare option: the host's raw {id, expr} declaration list. It is never the derived host_roots a LiveView editor keeps (a MapSet.t(String.t()) of root ids, built for undeclared-path advisories) - StatifierBlocks.Compiler.DeclaredRoots.declarations/1 answers a MapSet with {:error, [{:invalid_declaration, _}]}, so passing one here would fail every compile.

Summary

Types

status()

:no_fixtures - the fixtures source is nil, or holds no table for any block. :compile_error - the document does not compile (normal mid-edit, not exceptional); findings carries why. :ready - every row in runs was driven.

t()

Functions

run(document, palette, fixtures, opts \\ [])

Compiles document against palette once and drives every fixture row in fixtures once, returning a t().

Types

status()

@type status() :: :no_fixtures | :compile_error | :ready

:no_fixtures - the fixtures source is nil, or holds no table for any block. :compile_error - the document does not compile (normal mid-edit, not exceptional); findings carries why. :ready - every row in runs was driven.

t()

@type t() :: %StatifierBlocks.Runtime.FixtureRuns{
  failure_count: non_neg_integer(),
  findings: [StatifierBlocks.Compiler.Finding.t()],
  row_count: non_neg_integer(),
  runs: [StatifierBlocks.Runtime.FixtureRuns.Run.t()],
  status: status()
}

Functions

run(document, palette, fixtures, opts \\ [])

@spec run(
  StatifierBlocks.Document.t(),
  StatifierBlocks.Palette.t(),
  StatifierBlocks.Shell.fixtures(),
  keyword()
) :: t()

Compiles document against palette once and drives every fixture row in fixtures once, returning a t().

opts is the compiler's own option list, plus one option of this module's own. Every key but :view_model is forwarded verbatim to StatifierBlocks.Compiler.compile/3: a row is driven through the chart the document compiles to, and terminate:, child_use:, known_invoke_types: and datamodel: each change what that chart is. A caller that compiles with them and asks for fixture runs without them is asking about a different chart. Nothing here validates the list - the compiler is the authority on its own options.

  • :declare - the compiler's own :declare option. Defaults to []. This is the host's raw {id, expr} declaration list, never the derived host_roots MapSet a LiveView editor keeps - see the moduledoc.
  • :view_model - an already-built %StatifierBlocks.ViewModel{}, and the one key this module keeps for itself. A caller that already has one (an editor always does) should pass it rather than have this function build a second one. When absent, this function builds its own with ViewModel.build(document, palette, []).