Diagnósticos y Advertencias

Achronyme reporta errores y advertencias con fragmentos de código fuente, carets de subrayado y sugerencias accionables — similar a rustc. El sistema de diagnósticos funciona en todos los comandos (run, compile, circuit, disassemble).

Salida de Errores

Por defecto, los errores se renderizan con contexto del código fuente:

error: undefined variable: `conuter`
 --> 3:9
  |
3 | let y = conuter + 1
  |         ^^^^^^^
  |
  = help: did you mean `counter`?

La salida incluye:

• Severidad — error o warning, con un código opcional como [W001]
• Ubicación — archivo:línea:columna (o línea:columna para stdin)
• Fragmento de código — la línea ofensora con carets de subrayado (^^^)
• Etiquetas — spans secundarios apuntando a ubicaciones relacionadas
• Notas — contexto adicional (= note: ...)
• Sugerencias — correcciones accionables (= help: ...)

Advertencias del Compilador

El compilador emite advertencias para código que es válido pero probablemente incorrecto. Las advertencias nunca impiden la compilación.

W001: Variable No Utilizada

Se activa cuando una variable local o parámetro de función nunca se lee:

let count = 42
// warning[W001]: unused variable: `count`

Prefija con _ para silenciar la advertencia:

let _count = 42  // sin advertencia

W002: Mutable No Utilizado

Se activa cuando una variable se declara con mut pero nunca se reasigna:

let mut total = 0
print(total)
// warning[W002]: variable `total` declared as mutable but never mutated

Elimina la palabra clave mut si la variable no necesita cambiar.

W003: Código Inalcanzable

Se activa cuando hay sentencias después de un return en el mismo bloque:

fn foo() {
    return 1
    let x = 2  // warning[W003]: unreachable code
}

W004: Sombreado de Variables

Se activa cuando una nueva vinculación sombrea una variable existente en el mismo ámbito:

let x = 1
let x = 2  // warning[W004]: variable `x` shadows a previous binding in the same scope

W005: Import Selectivo No Utilizado

Se activa cuando un nombre traído por un import selectivo nunca se usa:

import { add, PI } from "./math.ach"
print(add(1, 2))
// warning[W005]: imported name `PI` is never used

Prefija con _ para silenciar la advertencia:

import { add, _PI } from "./math.ach"
print(add(1, 2))  // sin advertencia para _PI

Esta advertencia solo aplica a imports selectivos (import { ... } from). Los imports de namespace (import "..." as alias) no se verifican porque el alias es un solo binding.

Sugerencias “¿Quisiste Decir?”

Cuando el compilador encuentra una variable no definida, busca en todos los nombres en ámbito (locales, globales, upvalues) identificadores similares usando distancia de Levenshtein. Si encuentra una coincidencia cercana, sugiere la corrección:

error: undefined variable: `prnt`
 --> 2:1
  |
2 | prnt("hello")
  | ^^^^
  |
  = help: did you mean `print`?

El umbral de sugerencia escala con la longitud del nombre — nombres cortos (3 caracteres o menos) requieren una coincidencia más cercana para evitar sugerencias falsas.

Formatos de Salida

La bandera --error-format controla cómo se renderizan los diagnósticos. Se aplica globalmente a todos los subcomandos.

human (predeterminado)

Salida enriquecida con fragmentos de código, carets de subrayado y colores ANSI (cuando stderr es una terminal):

ach run program.ach --error-format human

json

Un objeto JSON por diagnóstico (formato JSON Lines), ideal para integraciones con editores y pipelines de CI:

ach run program.ach --error-format json

{"code":"W001","level":"warning","message":"unused variable: `x`","notes":["if this is intentional, prefix with underscore: `_x`"],"spans":[{"byte_end":5,"byte_start":4,"column_end":6,"column_start":5,"file_name":null,"label":"primary","line_end":1,"line_start":1}],"suggestions":[]}

Cada objeto JSON contiene:

Campo	Tipo	Descripción
message	string	El mensaje del diagnóstico
code	string|null	Código de advertencia/error (ej., "W001")
level	string	"error", "warning", "note", o "help"
spans	array	Ubicaciones en el código fuente con offsets de bytes, línea/columna y etiquetas
notes	array	Cadenas de contexto adicional
suggestions	array	Reemplazos de código sugeridos con spans

short

Formato compacto de una línea, compatible con grep:

ach run program.ach --error-format short

<stdin>:3:9: error: undefined variable: `x`

Formato: archivo:línea:columna: severidad: mensaje

Recuperación de Errores

El parser recopila múltiples errores por compilación en lugar de detenerse en el primero. Las regiones fallidas aparecen como nodos Error en el AST, permitiendo al parser continuar y reportar problemas adicionales:

$ ach compile broken.ach
error: expected expression
 --> 1:9
  |
1 | let x =
  |         ^
  |
error: unexpected token `}`
 --> 3:1
  |
3 | }
  | ^
  |

Esto significa que una sola ejecución de compilación puede revelar múltiples problemas a la vez, reduciendo el ciclo de editar-compilar-corregir.