HashQL Diagnostic Writing

HashQL Diagnostic Writing

Provides HASH-specific patterns for writing high-quality diagnostics using the hashql-diagnostics crate, ensuring messages are helpful, actionable, and follow consistent style conventions.

Core Principles

Diagnostics should be helpful, not just correct:

✅ DO:

• Start messages with lowercase
• Use backticks for code elements: expected `bool`, found `String`
• Make messages actionable and specific
• Use "invalid" not "illegal"
• Keep help messages as imperatives: "add type annotations"

❌ DON'T:

• End messages with punctuation (unless multi-sentence)
• Use apologetic language ("sorry", "unfortunately")
• Write vague messages ("something went wrong")
• Capitalize message starts (unless code identifier)

Quick Reference

Creating a Diagnostic

use hashql_diagnostics::{Diagnostic, Label, Message, Severity};

let mut diagnostic = Diagnostic::new(category, Severity::Error)
    .primary(Label::new(span, "expected `bool`, found `String`"));

diagnostic.add_label(Label::new(other_span, "expected because of this"));
diagnostic.add_message(Message::help("try using a comparison"));

Severity Levels

| Severity | When to Use |