Caravela.Errors (Caravela v0.13.3)

Copy Markdown View Source

Structured compile-time errors for Caravela's DSL and generators.

Distinct from Caravela.Error (which is the runtime result struct returned from context / generator functions as {:error, %Caravela.Error{}}). These are exceptions: thrown during DSL macro expansion or generator execution when a caller's input is malformed.

Two exception modules cover the surface:

  • Caravela.DSLError — raised from inside DSL macros (entity, field, policy, authenticatable, …) at compile time.
  • Caravela.GenError — raised from Caravela.Gen.* functions and mix caravela.gen.* tasks at generator-run time.

Both carry the same four-part shape: what went wrong, what Caravela got (a code snippet), a suggested fix, and a docs URL. Exception.message/1 renders the four parts consistently so humans, CI, and LLMs all see the same structured output.

Why structured

Freeform raise ArgumentError, "bad field" strings are fine for humans reading a terminal but painful for LLM iteration loops — the model has to guess what to fix from one line of prose. Structured errors let the LLM latch onto the Suggestion: block and patch correctly on the first try. Same benefit applies to humans opening a stack trace from CI without immediate editor context.

Example rendered output

** (Caravela.DSLError) `field :title` is missing a type

   Got:
       field :title

   Suggestion:
       field :title, :string, required: true

   See: https://hexdocs.pm/caravela/dsl.html#fields

Summary

Functions

dsl(env, fields)

Build a Caravela.DSLError from a Macro.Env (__CALLER__) plus message and suggestion. A convenience for macro authors.

gen(fields)

Build a Caravela.GenError for a generator-level failure.

snippet_from_env(arg1)

Extract ~3 lines of source around env.line for a snippet.

Functions

dsl(env, fields)

@spec dsl(
  Macro.Env.t() | nil,
  keyword()
) :: Caravela.DSLError.t()

Build a Caravela.DSLError from a Macro.Env (__CALLER__) plus message and suggestion. A convenience for macro authors.

raise Caravela.Errors.dsl(__CALLER__,
        message: "field requires a type",
        suggestion: "field :title, :string")

gen(fields)

@spec gen(keyword()) :: Caravela.GenError.t()

Build a Caravela.GenError for a generator-level failure.

snippet_from_env(arg1)

@spec snippet_from_env(Macro.Env.t() | nil) :: String.t() | nil

Extract ~3 lines of source around env.line for a snippet.