Skip to content

v0.14-diagnostics.md

Latest commit

 

History

History
191 lines (130 loc) · 2.99 KB

v0.14-diagnostics.md

File metadata and controls

191 lines (130 loc) · 2.99 KB
Raw

Sona v0.14 Diagnostics Guide

This page is the canonical user-facing diagnostics contract for Sona 0.15.1.

Documentation truth rule: if this page and runtime behavior disagree, runtime behavior wins and this page must be corrected before release.

Output Contract

Sona command-line diagnostics use this compact shape:

SonaXError: short summary
  at path/to/file.sona:line:column: source line
  hint: one actionable next step

Rules:

  • Errors print to stderr.
  • Error exits are nonzero.
  • Stack traces are hidden by default.
  • Hints are one line, actionable, and specific.
  • Normal runs must not print parser, interpreter, or debug setup noise.

Error Modes

sona run supports three error output modes:

Mode Command Behavior
Explain sona run file.sona --errors=explain Default compact diagnostic only.
Trace sona run file.sona --errors=trace Python traceback for runtime debugging.
Both sona run file.sona --errors=both Compact diagnostic first, traceback second.

Use explain for normal development and teaching. Use trace or both when debugging Sona internals or filing a runtime bug.

Common Diagnostics

Missing File

Command:

sona run missing.sona

Shape:

SonaFileError: file not found: missing.sona
  hint: check the path and run the command again.

Fix:

sona run hello.sona

Syntax Error

Broken code:

print("missing close);

Shape:

SonaSyntaxError: ...
  at syntax.sona:1: print("missing close);
  hint: check punctuation, quotes, and balanced brackets.

Fix:

print("missing close");

Undefined Name

Broken code:

print(total);

Shape:

SonaNameError: ...
  hint: declare it with let before using it.

Fix:

let total = 5;
print(total);

Import Typo

Broken code:

import mathh;

Shape:

SonaImportError: module 'mathh' not found
  hint: did you mean 'math'?

Fix:

import math;
print(math.add(2, 3));

If no close match exists, Sona prints:

hint: check the module name and that it is available.

Type Error

Broken code:

let total = 1 + [2];

Shape:

SonaTypeError: ...
  hint: check the value and arguments used in this call.

Fix by combining compatible values:

let total = 1 + 2;
print(total);

Runtime Error

Runtime errors that do not fit a narrower category use:

SonaRuntimeError: short summary

Use --errors=both when the compact message is not enough to identify the underlying runtime path.

Usage Errors

Invalid CLI usage uses SonaUsageError.

Examples:

sona
sona run
sona --unknown

Shape:

SonaUsageError: ...
  hint: use 'sona --help' for available commands.

First Debugging Steps

  1. Read the first SonaXError: line.
  2. Follow the hint: line.
  3. Check the at ... line for file and source context.
  4. Rerun with --errors=both only if you need the traceback.