Error System

Sassy’s error handling is provided by @gesslar/toolkit through two classes: Sass and Tantrum.

Sass

An enhanced Error with trace context chains. Rather than relying solely on JavaScript stack traces, Sass errors accumulate domain-specific context as they propagate up through the pipeline.

Sass.new("Variable not found")
  .trace("evaluating $(unknown.var)")
  .trace("in theme.colors['editor.background']")
  .trace("compiling ocean-theme.yaml")

Key Methods

• .addTrace(message) / .trace(message) — add a context layer. Traces are stored LIFO (most recent first when reading).
• .report(nerdMode) — format for terminal output.
  • Default mode: clean multi-line trace showing domain context only.
  • Nerd mode (--nerd flag): adds pruned JavaScript stack frames alongside domain context.

Usage Pattern

Errors are caught at each layer and re-wrapped with additional context:

try {
    // compilation work
  } catch(error) {
    throw Sass.new(\`Compiling \${theme.getName()}\`, error)
  }

This builds a chain of context from the point of failure up to the session level.

Source Location Enrichment

When a YAML file has been parsed with YamlSource, errors can include precise origin information. The Evaluator calls theme.findSourceLocation(dottedPath) to resolve a token’s dotted path back to its source position. When found, the location is added as a trace entry in file:line:col format:

Sass.new("Unknown variable $(missing)")
  .trace("palette.yaml:12:5")
  .trace("evaluating palette.accent")

This makes it straightforward to jump directly to the problematic line in an editor, especially in themes composed from many imported files.

Tantrum

An AggregateError that auto-wraps plain Error instances in Sass. Used when multiple errors need to be reported together.

• Collects errors from parallel operations
• .report(nerdMode) formats all contained errors

Per-Theme Isolation

Session uses Promise.allSettled to process themes. A failure in one theme produces a Sass-wrapped error report for that theme without halting compilation of the others. This is the primary consumer of Tantrum — when multiple themes fail, their errors are aggregated.