Letterpress.Diagnostic (Letterpress v0.1.0)

A stable, LSP-shaped diagnostic returned by Letterpress operations.

Ranges use zero-based UTF-16 line and character coordinates so the same positions work in Elixir responses and browser editors. source_hash and document_version let a host discard stale asynchronous results.

Diagnostic codes and the JSON shape are public contract. English messages are written for people and may improve between releases; application logic should match on code and, when needed, structured data.

Example

iex> diagnostic =
...>   Letterpress.Diagnostic.simple("LP_SCHEMA_UNUSED_VARIABLE", "Check this value", :warning)
iex> {diagnostic.code, diagnostic.severity, diagnostic.range.start}
{"LP_SCHEMA_UNUSED_VARIABLE", :warning, %{line: 0, character: 0}}

Summary

Types

point()

A zero-based UTF-16 document position.

range()

A half-open source range from :start to :end.

severity()

Severity understood by ExDoc consumers and LSP-compatible editors.

t()

A version-1 Letterpress diagnostic.

Functions

errors?(diagnostics)

Returns whether a list contains an error diagnostic.

from_maps(maps)

Converts compiler diagnostic maps into t/0 structs.

simple(code, message, severity \\ :error)

Creates a document-level diagnostic for local validation.

system(reason, profile, source, opts)

Creates a redacted diagnostic for a compiler or runtime boundary failure.

to_map(diagnostic)

Returns the string-keyed JSON projection of a diagnostic.

Types

point()

@type point() :: %{line: non_neg_integer(), character: non_neg_integer()}

A zero-based UTF-16 document position.

range()

@type range() :: %{start: point(), end: point()}

A half-open source range from :start to :end.

severity()

@type severity() :: :error | :warning | :information | :hint

Severity understood by ExDoc consumers and LSP-compatible editors.

t()

@type t() :: %Letterpress.Diagnostic{
  code: String.t(),
  data: map(),
  document_version: non_neg_integer(),
  message: String.t(),
  range: range(),
  related: [map()],
  severity: severity(),
  source: String.t(),
  source_hash: String.t(),
  version: 1
}

A version-1 Letterpress diagnostic.

Functions

errors?(diagnostics)

@spec errors?([t()]) :: boolean()

Returns whether a list contains an error diagnostic.

Example

iex> warning =
...>   Letterpress.Diagnostic.simple("LP_SCHEMA_UNUSED_VARIABLE", "Heads up", :warning)
iex> error = Letterpress.Diagnostic.simple("LP_SCHEMA_INVALID", "Stop")
iex> Letterpress.Diagnostic.errors?([warning, error])
true

from_maps(maps)

@spec from_maps([map()]) :: [t()]

Converts compiler diagnostic maps into t/0 structs.

Only the four known severity strings become atoms. Unknown severities fall back to :error, and missing optional fields receive contract defaults.

simple(code, message, severity \\ :error)

@spec simple(String.t(), String.t(), severity()) :: t()

Creates a document-level diagnostic for local validation.

The range points to the start of the document, and the severity defaults to :error.

system(reason, profile, source, opts)

@spec system(term(), String.t(), String.t(), keyword()) :: t()

Creates a redacted diagnostic for a compiler or runtime boundary failure.

The returned diagnostic preserves the profile, source hash, and document version but never copies template source or resolved values into its message or data.

to_map(diagnostic)

@spec to_map(t()) :: map()

Returns the string-keyed JSON projection of a diagnostic.

Severity becomes a string; range point keys also become strings. The result contains only JSON-native values when the struct came from Letterpress.