Vox diagnostic UX taxonomy (research)
Vox diagnostic UX taxonomy (research)
Section titled “Vox diagnostic UX taxonomy (research)”Naming: Planned slug vox-diagnostic-ux-ssot-2026; not B-canon until registered in contracts/documentation/canonical-map.v1.yaml.
Parent context: Vox Language Rules & Enforcement — Top-Level Plan (2026), Phase 2 (--for-llm, LintFix), Phase 4 (idiom telemetry hooks).
| Consumer | Need |
|---|---|
| Human in IDE | Stable severity, actionable spans, optional related information. |
| LLM agent | Stable machine-readable codes, minimal repro, symmetric fix hints (Phase 2). |
| CI | Same codes as local vox check; no duplicate conflicting rules without documented precedence. |
Namespace conventions
Section titled “Namespace conventions”- Prefer hierarchical IDs:
vox/<category>/<kebab-case>for new mesh/language work (mesh phase 1 plan). - Typechecker-owned codes live in
vox-compiler; extended detectors live invox-code-audit— document collisions in language-diagnostic-drift-findings-2026.md.
Severity ladder
Section titled “Severity ladder”| Level | Typical use |
|---|---|
| Error | Program rejected or unsound boundary crossed. |
| Warning | Correctness or policy risk; may become error after deprecation window. |
| Note / info | Optional style, migration nudges, education (map carefully to LSP Hint vs Information). |
LSP mapping
Section titled “LSP mapping”The language server maps TypeckSeverity to LSP DiagnosticSeverity and attaches structured fix data (crates/vox-lsp/src/lib.rs). Gaps to track:
- Whether every compiler diagnostic intended for authors appears in LSP validation.
- Whether
code_descriptionURLs (--explain) exist per Phase 2 plan.
CLI envelope (vox check --for-llm)
Section titled “CLI envelope (vox check --for-llm)”Shipped shape: vox check <file>.vox --for-llm prints a single JSON object (CheckForLlmEnvelope in crates/vox-cli/src/pipeline.rs):
| Field | Meaning |
|---|---|
envelope_version | Integer schema revision (currently 1). |
file_path | Label passed to check_file (usually the .vox path). |
ok | true only when zero error-severity diagnostics are present. |
error_count / warning_count | Aggregates over machine payloads (parse + typecheck + HIR validation). |
diagnostics | Array of VoxCompilerDiagnosticPayload structs (same JSON shape as legacy --json diagnostic arrays, wrapped). |
Golden lock: crates/vox-cli/tests/check_for_llm_envelope.rs.
Open questions
Section titled “Open questions”- Precedence: When
vox-code-auditandvox-compilerdisagree, which wins in CI vs IDE? - Formatting: Can
vox fmtchange spans such that diagnostics shift — see formatter findings doc. - Privacy: Which diagnostic payloads are safe for default telemetry vs opt-in — telemetry-trust-ssot.md.