@spec default_source() :: Lotus.Source.Adapter.t()

Returns the default source as an %Adapter{} struct.

@spec editor_config(Lotus.Source.Adapter.t() | String.t()) :: map()

Return the editor configuration for a source.

@spec example_query(
  Lotus.Source.Adapter.t() | String.t(),
  String.t(),
  String.t() | nil
) :: String.t()

Return an example query string suitable for placeholder text.

@spec get_source!(String.t()) :: Lotus.Source.Adapter.t()

Gets a source adapter by name. Raises if not found.

@spec hierarchy_label(Lotus.Source.Adapter.t() | String.t()) :: String.t()

Return the human-readable label for the top-level hierarchy in a source.

@spec limit_query(
  Lotus.Source.Adapter.t() | String.t(),
  Lotus.Query.Statement.t(),
  pos_integer()
) ::
  Lotus.Query.Statement.t()

Wrap a statement with a limit clause using the source's syntax.

@spec list_sources() :: [Lotus.Source.Adapter.t()]

Lists all configured source adapters.

@spec prepare_for_analysis(
  Lotus.Source.Adapter.t() | String.t(),
  Lotus.Query.Statement.t()
) ::
  {:ok, Lotus.Query.Statement.t()} | {:error, term()}

Ask the adapter to resolve a statement into a form suitable for optimization analysis (e.g. neutralizing {{var}} placeholders and stripping [[...]] optional clauses so the engine's EXPLAIN / profile endpoint can parse it).

Returns {:error, :unsupported} when the adapter does not implement prepare_for_analysis/2 — callers should treat that as "skip optimization for this source".

@spec query_language(Lotus.Source.Adapter.t() | String.t()) :: String.t()

Return the query language identifier for a source.

@spec resolve!(nil | String.t() | module(), nil | String.t() | module()) ::
  Lotus.Source.Adapter.t()

Resolve to an %Adapter{} struct.

Accepts:

• source_opt — configured name (string) or source module (atom) or nil
• q_source — query's stored source (string or module) or nil

Falls back to the default source. Raises on resolution failure.

@spec source_type(Lotus.Source.Adapter.t() | module() | String.t()) ::
  Lotus.Source.Adapter.source_type()

Detect the source type from an adapter, repository module, or name.

@spec supported_filter_operators(Lotus.Source.Adapter.t() | String.t()) :: [atom()]

Return the Lotus.Query.Filter operators this source's adapter supports.

UIs that expose a filter operator dropdown should read this list and gate the options per source — attempting to use an operator outside the declared list raises Lotus.UnsupportedOperatorError when filters are applied.

@spec supports_feature?(Lotus.Source.Adapter.t() | String.t() | module(), atom()) ::
  boolean()

Whether a source supports a specific feature.

Accepts an %Adapter{} struct or a source name/repo module (resolved to adapter).