writing-hashql-diagnostics

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
Bug	Internal compiler error
Fatal	Unrecoverable error
Error	Must be fixed to compile
Warning	Suspicious code to review
Note	Informational context

Message Style

// ✅ Good
"cannot find variable `count` in this scope"
"expected `;` after expression"

// ❌ Bad
"Error: Variable not found."  // capitalized, punctuation
"Sorry, there's a type mismatch"  // apologetic

Adding Suggestions

use hashql_diagnostics::{Message, Patch, Suggestions};

let suggestion = Suggestions::patch(Patch::new(span, "corrected_code"));
diagnostic.add_message(
    Message::help("fix the typo").with_suggestions(suggestion)
);

References

• Comprehensive guidelines - Complete message style guide, span selection, category design, label usage, help vs note, suggestion quality, review checklist
• HashQL testing skill - For compiletest coverage