diagnostic

Types

Diagnostic

Unified diagnostic type for all pipeline phases.

pub type Diagnostic {
  Diagnostic(
    code: String,
    phase: Phase,
    severity: Severity,
    target: Target,
    pointer: String,
    source_loc: SourceLoc,
    message: String,
    hint: option.Option(String),
  )
}

Constructors

Diagnostic(
  code: String,
  phase: Phase,
  severity: Severity,
  target: Target,
  pointer: String,
  source_loc: SourceLoc,
  message: String,
  hint: option.Option(String),
)

Phase

</>

Pipeline phase that produced the diagnostic.

pub type Phase {
  PhaseParse
  PhaseNormalize
  PhaseResolve
  PhaseCapabilityCheck
  PhaseValidate
  PhaseCodegen
}

Constructors

```
PhaseParse
```
```
PhaseNormalize
```
```
PhaseResolve
```
```
PhaseCapabilityCheck
```
```
PhaseValidate
```
```
PhaseCodegen
```

Severity

</>

Severity level for diagnostics.

pub type Severity {
  SeverityError
  SeverityWarning
}

Constructors

```
SeverityError
```
```
SeverityWarning
```

SourceLoc

</>

Source location from YAML/JSON parsing.

pub type SourceLoc {
  SourceLoc(line: Int, column: Int)
  NoSourceLoc
}

Constructors

```
SourceLoc(line: Int, column: Int)
```
```
NoSourceLoc
```

Target

</>

Target indicating which generation mode the issue applies to.

pub type Target {
  TargetBoth
  TargetClient
  TargetServer
}

Constructors

```
TargetBoth
```
```
TargetClient
```
```
TargetServer
```

Values

capability

</>

pub fn capability(
  path path: String,
  detail detail: String,
  severity severity: Severity,
  target target: Target,
  hint hint: option.Option(String),
  loc loc: SourceLoc,
) -> Diagnostic

Issue #411: capability checks now thread a YAML SourceLoc through every diagnostic. Pass NoSourceLoc only when the caller genuinely has no LocationIndex available (e.g. tests that bypass the parser path); production code always has one because it goes through parser.parse_file_with_locations / generate.generate_with_locations.

errors_only

</>

pub fn errors_only(issues: List(Diagnostic)) -> List(Diagnostic)

Filter to only errors (not warnings).

file_error

</>

pub fn file_error(detail detail: String) -> Diagnostic

filter_by_mode

</>

pub fn filter_by_mode(
  issues: List(Diagnostic),
  mode: config.GenerateMode,
) -> List(Diagnostic)

Filter diagnostics to those relevant for the selected generation mode.

invalid_value

</>

pub fn invalid_value(
  path path: String,
  detail detail: String,
  loc loc: SourceLoc,
) -> Diagnostic

missing_field

</>

pub fn missing_field(
  path path: String,
  field field: String,
  loc loc: SourceLoc,
) -> Diagnostic

render

</>

pub fn render(
  d: Diagnostic,
  file_path file_path: option.Option(String),
) -> String

Render a diagnostic with an editor-clickable path:line:column: prefix when the spec file path and a SourceLoc are both known. Falls back to plain to_string otherwise.

Issue #411: CI runs that process several specs need a breadcrumb to which file produced an error; editors recognise the path:line:col: prefix and let users jump straight to the offending YAML line.

resolve_error

</>

pub fn resolve_error(
  path path: String,
  detail detail: String,
  hint hint: option.Option(String),
  loc loc: SourceLoc,
) -> Diagnostic

to_short_string

</>

pub fn to_short_string(d: Diagnostic) -> String

Convert a diagnostic to a short string (for backward-compatible display).

to_string

</>

pub fn to_string(d: Diagnostic) -> String

Convert a diagnostic to a human-readable string.

validation

</>

pub fn validation(
  path path: String,
  detail detail: String,
  severity severity: Severity,
  target target: Target,
  hint hint: option.Option(String),
) -> Diagnostic

validation_error_both

</>

pub fn validation_error_both(
  path path: String,
  detail detail: String,
  hint hint: option.Option(String),
) -> Diagnostic

Issue #416: severity / target shortcut builders for the common validation shapes used in internal/codegen/validate. The project review noted that the 5-field validation/5 constructor gets called 28+ times with the same severity / target pair on almost every site; these helpers collapse the common shape and let call sites focus on the variable bits (path / detail / hint). SeverityError + TargetBoth — the most common shape across validate.gleam.

validation_error_server

</>

pub fn validation_error_server(
  path path: String,
  detail detail: String,
  hint hint: option.Option(String),
) -> Diagnostic

SeverityError + TargetServer — the second most common shape (server-only feature restrictions).

validation_warning_both

</>

pub fn validation_warning_both(
  path path: String,
  detail detail: String,
  hint hint: option.Option(String),
) -> Diagnostic

SeverityWarning + TargetBoth — used when a spec shape is supported but the user should know about it.

warnings_only

</>

pub fn warnings_only(
  issues: List(Diagnostic),
) -> List(Diagnostic)

Filter to only warnings (not errors).

yaml_error

</>

pub fn yaml_error(
  detail detail: String,
  loc loc: SourceLoc,
) -> Diagnostic