Vitte

Vitte Diagnostics

Quick consultation of diagnostics: a code, a layer, a correction.

Welcome Documentation Sitemap Download Source Community News Diagnostics Suggestions

Source of truth

The active diagnostics surface is the Vitte compiler itself. For implementation details, start from src/vitte/compiler/diagnostics/diagnostic.vit and the technical note docs/compiler/diagnostics.md. The bootstrap seed diagnostics described in docs/seed_diagnostics.md are a narrower stage0 contract, not the full compiler surface.

Official sequence

  • vitte check <file>
  • vitte check --diagnostics-json <file>
  • vitte --dump-ast-json <file>
  • vitte --dump-hir-json <file>
  • vitte --dump-mir-json <file>

Stable JSON surface

  • schema = "vitte.compiler.surface"
  • surface = "diagnostics"
  • valid tells whether the request succeeded
  • pipeline_failed_at identifies the first failing stage
  • primary_report.diagnostics[] contains the flattened report
  • phase_reports.* keeps per-phase diagnostics

Phase map

  • frontend : lexer, parser, ast_validation
  • resolution : module_resolution, symbol_resolution, sema
  • middle-end : hir, typeck, borrowck, mir, mir_lowering, mir_verification, ir
  • backend : backend, linker, runtime_execution
  • driver : CLI/input/configuration failures before or around the pipeline

Frequent codes

  • PARSE_E_UNCLOSED_BLOCK - parser reached EOF before a closing delimiter
  • E1005 - unknown identifier
  • TYPECK_E_ASSIGN_MISMATCH - assignment type mismatch
  • BORROWCK_E_USE_AFTER_MOVE - moved value used later
  • LIMIT_FILE_SIZE_MAX - source exceeds hard input-size policy

What to do first

  • Read the first failing phase and code, not the whole waterfall.
  • Reduce the repro to the smallest file that still fails.
  • Re-run with --diagnostics-json when you need machine-readable detail.
  • Use AST/HIR/MIR JSON dumps only after the frontend phase is clean enough to progress.

Quick index

  • parse : malformed syntax, recovery diagnostics, unclosed delimiters.
  • resolve : missing modules, symbols, visibility and name binding issues.
  • typeck : incompatible assignments, call arity/type mismatches, non-exhaustive matches.
  • borrowck : use-after-move, borrow conflicts, lifetime failures.
  • driver : invalid CLI input, path/policy issues, hardening limits.

Example

space sample

proc main() -> void {
  let x = 1
  give x + "bad"
}

This minimal example is useful for understanding diagnostics: the compiler can parse the code, but it will fail later with a type mismatch because int + string is invalid. Reduce the repro to this smallest form when you triage a failure.

Practical reading

Diagnostics should be read as a contract, not as a wall of text. The phase tells you where the pipeline stopped, the code names the stable failure class, and the JSON envelope lets you inspect the same event without scraping text output.

For a fast triage, use this order:

  1. Identify pipeline_failed_at or the first human-visible phase.
  2. Read the primary code, message, label, note, and help.
  3. Reduce the repro to the smallest snippet that still fails.
  4. Re-run with --diagnostics-json if you need exact fields or per-phase separation.
  5. Only then move to AST/HIR/MIR dumps if the failing phase is past parsing.

That sequence keeps bug reports useful: the report should name the phase, the code, the smallest repro, and the expected behavior instead of only describing the symptom.

If you need a broader starting point, read Documentation for the compiler surface and Source for the implementation path.