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.

duplicate_key

</>

pub fn duplicate_key(
  path path: String,
  key key: String,
  loc loc: SourceLoc,
) -> Diagnostic

Issue #573: a YAML mapping at path contains the same key twice. yamerl tolerates duplicate mapping keys (only the last value survives), so this is the only signal users get that their spec silently dropped one of two definitions. Surfaced as a parse-phase error so oaspec validate rejects the file before generation.

key is the duplicated key as it appears in the source (e.g. "200" for a duplicated response status code, "foo" for a duplicated component name).

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

parse_limit_exceeded

</>

pub fn parse_limit_exceeded(
  limit limit: String,
  configured configured: Int,
  actual actual: Int,
) -> Diagnostic

Parser refused the input because it exceeded a configured DoS limit (see parser.ParseLimits). The message names the limit, the configured cap, and the actual value so callers can either bump the limit (when they trust the source) or reject the input.

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