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
1---2name: writing-hashql-diagnostics3description: HashQL diagnostic writing patterns using hashql-diagnostics crate. Use when creating error messages, warnings, Labels, Messages, Severity levels, Patches, Suggestions, or improving diagnostic quality in HashQL code.4license: AGPL-3.05metadata:6 source: https://skillmd.com/skills/hashintel/writing-hashql-diagnostics7 triggers:8 type: domain9 enforcement: suggest10 priority: high11 keywords:12 - diagnostic13 - hashql-diagnostics14 - Label15 - Message16 - Severity17 - Patch18 - Suggestions19 intent-patterns:20 - "\\b(create|write|add|improve)\\b.*?\\bdiagnostic\\b"21 - "\\b(error|warning)\\b.*?\\bmessage\\b"22---2324# HashQL Diagnostic Writing2526Provides HASH-specific patterns for writing high-quality diagnostics using the `hashql-diagnostics` crate, ensuring messages are helpful, actionable, and follow consistent style conventions.2728## Core Principles2930**Diagnostics should be helpful, not just correct:**3132✅ **DO:**3334- Start messages with lowercase35- Use backticks for code elements: `` expected `bool`, found `String` ``36- Make messages actionable and specific37- Use "invalid" not "illegal"38- Keep help messages as imperatives: "add type annotations"3940❌ **DON'T:**4142- End messages with punctuation (unless multi-sentence)43- Use apologetic language ("sorry", "unfortunately")44- Write vague messages ("something went wrong")45- Capitalize message starts (unless code identifier)4647## Quick Reference4849### Creating a Diagnostic5051```rust52use hashql_diagnostics::{Diagnostic, Label, Message, Severity};5354let mut diagnostic = Diagnostic::new(category, Severity::Error)55 .primary(Label::new(span, "expected `bool`, found `String`"));5657diagnostic.add_label(Label::new(other_span, "expected because of this"));58diagnostic.add_message(Message::help("try using a comparison"));59```6061### Severity Levels6263| Severity | When to Use |64| --------- | ------------------------- |65| `Bug` | Internal compiler error |66| `Fatal` | Unrecoverable error |67| `Error` | Must be fixed to compile |68| `Warning` | Suspicious code to review |69| `Note` | Informational context |7071### Message Style7273```rust74// ✅ Good75"cannot find variable `count` in this scope"76"expected `;` after expression"7778// ❌ Bad79"Error: Variable not found." // capitalized, punctuation80"Sorry, there's a type mismatch" // apologetic81```8283### Adding Suggestions8485```rust86use hashql_diagnostics::{Message, Patch, Suggestions};8788let suggestion = Suggestions::patch(Patch::new(span, "corrected_code"));89diagnostic.add_message(90 Message::help("fix the typo").with_suggestions(suggestion)91);92```9394## References9596- [Comprehensive guidelines](references/guidelines.md) - Complete message style guide, span selection, category design, label usage, help vs note, suggestion quality, review checklist97- [HashQL testing skill](../testing-hashql/SKILL.md) - For compiletest coverage