Diagnostics | GistUI

Every diagnostic code a GistUI processor reports and every runtime error code, with severity, cause and effect.

A processor reports problems as diagnostics. A runtime reports problems as error actions. Codes are stable across versions; messages are for people and may change.

The diagnostic object

{
  code: "invalid-enum",
  severity: "warning",       // "error" | "warning"
  stmt: "card",              // the statement concerned, when there is one
  line: 4,                   // 1-based
  fixed: true,               // the processor repaired it and the tree shows the repair
  message: "…",              // for people
  hint, use, prop, arg, ref, // optional details
}

Get them from parse(source, library).errors, from a renderer’s onError, or from validateProgram on the server.

Processor codes

Code	Severity	Raised when	Effect
`prose-ignored`	warning	A line is not a statement, comment or fence	The line is ignored
`lenient-syntax`	warning	A recovery rule was applied	The text is read as the rule says; nothing is lost
`unterminated-string`	error, fixed	A string was still open at the line end	The string and the statement end there
`parse-failed`	error, fixed	A character was skipped, or text after the value was ignored	The statement is kept
`parse-failed`	error	The statement could not be read	The statement is dropped
`limit`	error	A processor limit was reached	See limits
`unsupported-version`	warning	The version pragma names an unknown major version	Processing continues
`reserved-id`	warning	A statement id is a flag name of the catalog	None; as a bare word the name means the flag
`unknown-component`	error, fixed	The name is not in the catalog and a close name was used	The closest component is used
`unknown-component`	error	The name is not in the catalog and nothing is close	An `#unknown` node
`unknown-prop`	warning	A named argument or patch names no prop	The argument is ignored
`missing-required`	error	A required prop has no value	The node is kept without the prop
`excess-args`	error, fixed	A positional argument has no place	The argument is ignored
`positional-optional`	warning	A prop that is not positional was passed by position	The prop is set
`invalid-prop`	warning	A value does not fit the prop type	The default, or no value
`invalid-enum`	warning, fixed	A value was corrected to a close enum value	The close value is used
`invalid-enum`	error	A value is not an enum value and nothing is close	The default, or no value
`invalid-child`	warning	A child is not accepted by its parent, or a data value is in child position	A component child is kept; a data value is dropped
`bare-text`	warning	A bare word that nothing defines was used as text	The word is the text
`blocked-url`	warning, fixed	A URL that loads by itself is refused	The URL is removed
`unresolved-ref`	error, fixed	A reference to an id that nothing defines	The reference is dropped
`cycle`	error, fixed	A statement contains itself	The reference that closes the loop is dropped
`patch-target-missing`	error	A patch or append has no valid target	The edit is ignored
`no-root`	warning, fixed	No statement `root`; the first component is used	That component is the root
`no-root`	error	There is no root	The tree is empty
`unreachable`	warning	A statement is not used	None

Runtime error codes

Reported to onAction as { type: "error", code, … }.

Code	Raised when	Effect
`tool-not-found`	A query or mutation names a tool that is not in its set	The call fails
`tool-failed`	A tool call failed, was refused by the host, or passed the call budget	The call fails; a mutation stops its action list
`blocked-url`	`@open` was refused, or a URL that loads by itself was refused at run time	The action list stops, or the URL is removed
`unknown-step`	An action step is not known	The action list stops
`limit`	A runtime limit was reached	See limits

Validity

const r = parse(source, library);
r.valid.strict;  // no diagnostics at all
r.valid.lenient; // everything that was wrong was repaired by a rule

A good generator produces strict programs. A good host accepts lenient ones.

Sending errors back to a model

For a model-assisted repair, send only the failing statements and their diagnostics: Autofix and repair.