Diagnostics · Glazier

The reason I started this project was to learn how Terraform validates its HCL, and the diagnostics are the part of that lesson I was most pleased to keep. A broken profile does not give you a stack trace or a one-line “invalid layout”. It gives you the file, the line, the offending text and a sentence that says what to do about it. Here is what that looks like and how to rely on it.

A real diagnostic

This profile asks for a layout that does not exist:

bad-layout.glaze
HCL
session {
  name = "daemon-run"

  window {
    name   = "ice-breaker"
    layout = "main-diagonal"

    pane {
      commands = ["nvim ./payloads"]
    }
  }
}

Console
$ glaze format --validate --profile-path bad-layout.glaze
Error: Invalid layout specified

  on bad-layout.glaze line 6, in session:
   6:     layout = "main-diagonal"

The layout value of "main-diagonal" is not a supported preset
(even-horizontal, even-vertical, main-horizontal, main-vertical, tiled) nor a
valid tmux layout string.

the glaze profile contains errors
$ echo $?
3

What a diagnostic contains

Part	Content
Severity and summary	`Error:` or `Warning:` and a short name for the problem.
Location	The file, the line and the block, when the problem has a place in a file.
Snippet	The source line, when Glazier can read the file.
Detail	What is wrong and, where possible, what to do.

A problem without a place in a file, for example an undeclared --var name, has no location and no snippet.

Rules

Glazier reports every problem it can find in one run. It does not stop at the first one. Thus one format --validate shows a duplicate variable, a malformed block and an unresolvable local together.
Glazier sorts the diagnostics: first those without a place, then the profile, then each other file by name, each from top to bottom.
A diagnostic that points into a --var-file shows the snippet from that file.
A warning does not change the exit code. An error does.
Glazier writes diagnostics to stderr. Only command output goes to stdout. Glazier writes colour only when stderr is a terminal. Set NO_COLOR to turn colour off.

Exit codes

Code	Meaning
`0`	Success.
`1`	A run failed, for example because tmux rejected an option value or Glazier could not write a profile.
`2`	The command line is not correct, for example an unknown flag or a `--var` without `=`.
`3`	The profile has errors, or Glazier cannot find the profile.
`4`	Glazier cannot reach tmux.
`130`	SIGINT, for example Ctrl-C, stopped Glazier.
`143`	SIGTERM stopped Glazier.

A profile error is always 3, so a script can tell a bad profile from a tmux failure. The full table with notes is on Global flags and exit codes.

Validation in CI

glaze format --validate decodes the profile, reports every diagnostic and exits with code 3 when one is an error. It needs no tmux server. Thus you can run it in CI.

Console
$ glaze format --validate --stdout --var district=watson > /dev/null

The --validate flag enforces the full variable contract. A required variable needs a value from --var, --var-file or a default, the same as up. Use --stdout so that the check never rewrites the file. See format and Scripting.

Common messages

Summary	Cause
`Missing session block`	The profile has no `session` block.
`Duplicate session block`	The profile has two `session` blocks.
`Unsupported argument`	An attribute that the block does not accept, for example `envs` on a window.
`Invalid layout specified`	A `layout` that is not a preset and not a valid raw layout string.
`Invalid session name specified`	The session `name` is empty.
`Invalid session name`	The session `name` uses `random()`.
`Required variable not set`	A variable without a default has no value.
`Undefined variable`	A `--var` or a var file sets a name that no `variable` block declares.
`Invalid variable value`	A value does not convert to the declared type.
`Circular reference between locals`	Locals refer to each other. See Locals.
`Nesting too deep`, `Locals too large`	The profile is past a limit. See Limits.
`Session name will be changed`	A warning: tmux would rewrite a character in the name, so Glazier replaces it with `-`.

The “report everything in one run” rule is the one I would fight for. A validator that stops at the first error turns a profile with six problems into six round trips, and by the fourth one you have stopped reading the message and started guessing. Glazier walks the whole file, collects everything it can, sorts it so that it reads top to bottom and prints it once. Fix the list, run it again, done.

A real diagnostic#

What a diagnostic contains#

Rules#

Exit codes#

Validation in CI#

Common messages#