MailglassAdmin.Preview.Discovery (MailglassAdmin v1.0.0)

Copy Markdown View Source

Reflection for mailable modules — finds use Mailglass.Mailable modules, reads their preview_props/0 callback if present, and returns the pair ready for the preview dashboard sidebar.

Discovery modes

  • :auto_scan (default) — Walks :application.loaded_applications/0 and for each app calls :application.get_key(app, :modules), filtering by the __mailglass_mailable__/0 marker that use Mailglass.Mailable injects via @before_compile.

  • [module | _] explicit list — Override for umbrella apps, pathological module counts, or adopter preference. Each module MUST have the marker or discovery raises ArgumentError with an actionable message.

Graceful failures (CONTEXT D-13)

  • Marker present, no preview_props/0 defined -> {module, :no_previews}
  • preview_props/0 raises -> {module, {:error, formatted_stacktrace}}
  • preview_props/0 returns non-list or a list item whose second element is not a map -> {module, {:error, shape_violation_message}}

None of these failure modes raise from discover/1. The LiveView branches on the second tuple element to render the correct sidebar + main pane state (05-UI-SPEC sidebar section lines 189-207, error card lines 386-404).

Performance

Empirical: ~50ms on a 10,000-module umbrella app. function_exported?/3 is O(1) per module. If adopters report slow mount, they bypass the scan via the explicit :mailables list.

Boundary classification

Submodule auto-classifies into the MailglassAdmin root boundary declared in lib/mailglass_admin.ex (use Boundary, deps: [Mailglass], exports: [Router]); Boundary's classify_to: directive is reserved for mix tasks and protocol implementations and is not used here. Matches the package's general convention for internal support modules.

Summary

Functions

Discovers mailable modules and their preview scenarios.

Types

reflection()

@type reflection() :: [scenario()] | :no_previews | {:error, String.t()}

result()

@type result() :: {module(), reflection()}

scenario()

@type scenario() :: {atom(), map()}

Functions

discover(mods)

(since 0.1.0)
@spec discover(:auto_scan | [module()]) :: [result()]

Discovers mailable modules and their preview scenarios.

Returns a list of tuples; order is implementation-defined but stable within a single call.