writing-hashql-diagnostics
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.
ソース情報
- リポジトリ
- hashintel/hash
- ソースの最終更新活動
- 2026年9月1日 07:54
- 検出された SKILL.md の言語
- 英語
- スター
- 1,666
- フォーク
- 123
インストール方法
デフォルトでは、最初にソースを確認する Prompt が選択されています。直接コマンドに切り替えるか、ローカルコピーをダウンロードすることもできます。
ソースファイルを確認
インストールを決める前に、SKILL.md と SkillsMP に表示されている付属ファイルをお読みください。
ファイルエクスプローラー
2 ファイルSKILL.md を表示中
SKILL.md
ソースの指示 · 読み取り専用プレビュー- name
- writing-hashql-diagnostics
- description
- 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.
- license
- AGPL-3.0
- metadata
- {"triggers":{"type":"domain","enforcement":"suggest","priority":"high","keywords":["diagnostic","hashql-diagnostics","Label","Message","Severity","Patch","Suggestions"],"intent-patterns":["\\b(create|write|add|improve)\\b.*?\\bdiagnostic\\b","\\b(error|warning)\\b.*?\\bmessage\\b"]}}
# 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
```rust
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
```rust
// ✅ 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
```rust
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](references/guidelines.md) - Complete message style guide, span selection, category design, label usage, help vs note, suggestion quality, review checklist
- [HashQL testing skill](../testing-hashql/SKILL.md) - For compiletest coverage
GitHubで見る