Debugging

The commands that actually help, and how to read a diagnostic.

vlatest

Debugging in PickleScript starts with a fast type-check, an AST dump, a stable error-code catalogue, and a history of which committed versions compiled.

Start with check

pickle check parses, resolves and type-checks without generating code. It is the fastest loop in the toolchain:

pickle-cli check src/main.pkl

Read the diagnostic

Every diagnostic carries a stable code, a message that says what happened, the source line, and a caret under the offending span. Codes never change meaning between releases, so they are safe to search for.

Range Area
E01xx Lexing and parsing
E02xx Declarations, name resolution, inheritance
E03xx Type checking and expressions
E04xx Operations, attributes, calls, memory builtins
E05xx Ownership and memory
E07xx Stored or returned references

A diagnostic with no code renders as (uncoded) rather than guessing one.

Look up any code

pickle explain prints the rule and a worked example, with no docs to install:

pickle-cli explain            # every code in the catalogue
pickle-cli explain E0343      # one code, with an example

The catalogue is also maintained as a page, see Diagnostics.

Look at the parse

When a construct is not doing what you expect, dump the tree the parser built:

pickle-cli ast src/main.pkl

The lexer has a matching dump: pickle lex prints the canonical token stream, one token per line, so you can compare what the lexer produced against what the parser expected.

History

Two commands answer "when did this break":

  • pickle history shows how public types and dependencies evolved across git history, so a type that changed shape has a visible origin.
  • pickle builds shows, newest first, which committed versions compiled and which failed, with the error codes of the failures.
pickle-cli builds

Between the two, a regression in a dependency is a lookup rather than an investigation.