En esta página

Guidedog / Documentación 0.2.0

Mensajes de error

Un diagnóstico debe identificar el problema, indicar su ubicación y proponer un paso útil. Guidedog conserva esa información como datos estructurados. El terminal añade color y marcas en el código. JSON mantiene los datos sin decoración.

Cómo leer un diagnóstico

UNDEFINED SUBSTITUTION                              rst.substitution.undefined

  guide/page.rst:4: See |logo| here.
                        ^^^^^^

The substitution "|logo|" is not defined.
No output was written.

Add a definition, e.g. ".. |name| replace:: text".

Un diagnóstico tiene cuatro partes, siempre en este orden:

1. La barra de título. Nombra el tipo de problema en mayúsculas; advertencias y notas empiezan por WARNING: y NOTE:. A la derecha aparece el código, como rst.substitution.undefined: un nombre estable que puede buscarse.
2. Dónde. Archivo y línea, el texto original y una marca bajo el fragmento afectado. Si el problema no corresponde a una línea, como una carpeta ausente o una opción, solo se muestra la ruta o nada.
3. Qué ocurrió. La explicación y, cuando importa, su efecto en la salida: en este caso, que no se escribió nada.
4. Qué hacer. La sugerencia, en verde en un terminal con color, da una instrucción concreta. Si hay varias soluciones, las enumera empezando por la más probable.

Los colores solo resaltan lo que ya dicen las palabras. --color=never los desactiva y --color=always los conserva aunque la salida no sea un terminal.

Cada sugerencia indica qué hacer

Guidedog aplica esta regla a sus mensajes: la ayuda empieza con una acción («Add», «Pass», «Set», «Rename», «Run») y su objeto, como --budget=MIB, root_doc en conf.toml o una opción de directiva. tests/hints_test.odin revisa todos los mensajes y rechaza ayudas vacías, repetidas o que solo dicen «report this» sin indicar qué aportar. También admite sugerencias que ya expresan la corrección («Did you mean numfig?») y notas sin acción con «Nothing to do:» y el motivo.

Si el fallo es de Guidedog, la sugerencia lo dice y pide comunicarlo con el comando ejecutado, la entrada que lo provocó y la salida de guidedog --version.

Diagnósticos para programas

--diagnostics=json escribe cada informe como un objeto JSON por línea en la salida de error, para editores e integración continua:

{"schema":1,"code":"rst.substitution.undefined","severity":"error",
 "title":"UNDEFINED SUBSTITUTION","message":"The substitution \"|logo|\" is not defined.",
 "hint":"Add a definition, e.g. \".. |name| replace:: text\".","path":"guide/page.rst",
 "line":4,"column":5,"end_line":4,"end_column":11,"source":"See |logo| here.",
 "category":""}

Aquí se muestra dividido; cada objeto ocupa una sola línea. schema es la versión del formato y cambia solo al cambiar un campo: compruébala primero. Las columnas cuentan escalares Unicode desde 1, no bytes ni celdas de terminal. source contiene la línea original completa. El terminal muestra una ventana acotada y alinea el marcador tras escapar controles y medir caracteres anchos. category es la categoría usada por suppress_warnings o está vacía.

Cuando se agota la memoria

Agotar la memoria también produce un diagnóstico, nunca un cierre inesperado. Hay dos casos:

host.budget (LÍMITE DE MEMORIA ALCANZADO)

La construcción alcanzó su presupuesto de memoria (--budget=MIB, 1 GiB por defecto). El informe identifica el paso y, en una plantilla, la línea solicitante. En un terminal pregunta una vez: aumentar el presupuesto, continuar con memoria de trabajo en disco o parar. Fuera del terminal se detiene; --budget o --memory=disk permiten elegir de antemano. La ayuda da ese presupuesto como número, por ejemplo:

Build again with --budget=256, or with --memory=disk to keep working memory on
disk (slower); or split the work into smaller files.

La cifra cubre lo ya retenido más cuatro veces el paso rechazado (que también guarda su salida y la copia escrita), o el doble del presupuesto anterior, lo que sea mayor, redondeado hacia arriba a 64 MiB. Si el paso cabe en la memoria libre, no supera esa cantidad. Si no cabe, la ayuda lo indica y propone primero --memory=disk:

Build again with --memory=disk to keep working memory on disk (slower): the step
needs a budget of about 1408 MiB, more than the 900 MiB this machine has free. Or
free that memory and build with --budget=1408, or split the document.

host.memory (MEMORIA INSUFICIENTE)

El sistema rechazó memoria permitida por el presupuesto. El comando para sin usarla: la construcción no publica, el cambio GDS se aplica entero o nada, y convert escribe una página entera o ninguna. Libera memoria o reduce hilos (-j 1) y repite. Tras decidir publicar, el cambio de salida no necesita memoria; un rechazo no puede interrumpirlo a medias. Si encuentra una publicación anterior pendiente y no puede planificarla por falta de memoria, la deja intacta para la próxima construcción.

Ambos terminan con estado 3.

Estado de salida

Cada comando termina con uno de estos estados, para que los scripts distingan los tipos de fallo:

Estado	Significado
0	Éxito. La salida se escribió y, en un build, se publicó.
1	Hay un problema en la entrada: error documental, rechazo de política (contenido sin procesar sin --raw), documento ilegible o advertencia tratada como error por -W o --strict.
2	Uso incorrecto del comando: opción o comando desconocido, valor ausente o inválido, o configuración inválida en conf.toml o -D.
3	Se alcanzó un límite: presupuesto de memoria (--budget), profundidad (--max-depth), nodos (--max-nodes), pila (--stack-kib), fuente demasiado grande o memoria que el sistema no pudo proporcionar.
4	Falló un archivo o programa externo: ruta que no se puede leer o escribir, archivo modificado durante la lectura, o Typst que no pudo iniciarse o terminar.
5	Guidedog falló internamente y el diagnóstico pide comunicarlo.
70	Al fallar, Guidedog muestra GUIDEDOG CRASHED (internal error), el comando, el fallo y la salida de guidedog --version. Indica el gestor de incidencias del build o, en su defecto, su proveedor. Como publica solo al final, el fallo conserva la salida anterior.
130	El comando se interrumpió con Ctrl+C; los archivos publicados no cambiaron.

Si una compilación falla por cualquier motivo, conserva la salida anterior y sus registros. Corrija el problema y vuelva a compilar.