codexivo 0.2.3 → 1.0.1

package/docs/arquitectura.md

@@ -29,6 +29,51 @@ código ──tokenize──▶ tokens ──parse──▶ AST ──compile─
 - Ante un error, el parser lo registra, salta hasta un punto seguro (un `;`, una `}`, una palabra que empieza sentencia o una
   línea nueva) y sigue. Así reporta varios errores en una pasada sin inventar errores en cascada.
 
+### Traza del parser
+
+`parse(código, { trace: true })` (o `traceParse(código)`) regresa además `trace`: los pasos con los que el parser construyó
+el árbol, en orden. Con eso el sitio puede animar **cómo** se construye, no solo mostrar el resultado. Cada evento es un
+objeto plano con su `span`:
+
+| Evento       | Qué cuenta                                                                                                     |
+| ------------ | -------------------------------------------------------------------------------------------------------------- |
+| `consume`    | El parser toma un token: `index` en `tokens`, `tokenType` y `lexeme`.                                          |
+| `enter`      | Empieza a construir un nodo (`kind`). Si lo construye a partir de uno ya hecho, `left` es el `id` de ese nodo. |
+| `exit`       | Termina el nodo: `kind` e `id`, el mismo `id` que tiene en el AST.                                             |
+| `precedence` | Decide de quién es un valor (ver abajo).                                                                       |
+| `error`      | Un error de sintaxis, con su `code` y `message` (el mismo que está en `errors`).                               |
+| `recover`    | Después de un error: qué nodos abiertos abandona y qué tokens salta para seguir.                               |
+
+**Nodos abiertos.** Entre el `enter` y el `exit` de un nodo, el nodo está abierto esperando a sus hijos, que son los nodos
+que terminan en medio. Un parser Pratt no sabe que `1` es el lado izquierdo de una suma hasta que ve el `+`: por eso el
+`enter` del `Binary` llega después del `exit` del `1` y lleva `left` con su `id`; la vista mueve ese nodo dentro del nuevo.
+Lo mismo pasa con las llamadas (`f` en `f(1)`), los índices, las asignaciones (`x` en `x = 1`) y las sentencias que son
+una expresión.
+
+**Precedencia.** Es la decisión central del parser. En `1 + 2 * 3`, después de leer `2` el parser está construyendo el lado
+derecho del `+` y llega el `*`. El evento lleva:
+
+- `operand`: el `id` del valor en disputa (el `2`);
+- `building`: el operador que está esperando ese valor (`+`) y la precedencia con la que compara; no viene si ningún
+  operador lo espera (al inicio de una expresión o dentro de un paréntesis);
+- `incoming`: el operador que llegó (`*`) y su precedencia;
+- `decision`: `se_lo_lleva` si `incoming` tiene más precedencia (el `2` pasa a ser el lado izquierdo del `*`) o `se_queda`
+  si no (el `2` se queda como lado derecho del `+`).
+
+En `(1 + 2) * 3` el paréntesis cierra la suma antes de que llegue el `*`: el evento del `*` no trae `building` y su
+`operand` es la suma completa. En `1 < 2 y 5 < 4`, el `2` se queda con el `<` porque la `y` tiene menos precedencia. Como
+`^` agrupa a la derecha, su lado derecho compara con una precedencia menos que la suya: en `2 ^ 3 ^ 2` el segundo `^` se
+lleva al `3`. Las llamadas, los índices y el `.` también tienen precedencia (la más alta) y producen su evento.
+
+**Errores.** Los nodos que estaban abiertos cuando falló la sentencia se abandonan: no tienen `exit` y no están en el AST.
+`recover` los lista (`abandoned`, del más interno al más externo) junto con los tokens que saltó (`skipped.from` hasta
+`skipped.to - 1`); el siguiente `consume` es el token `skipped.to`. Los errores léxicos no aparecen en la traza; el lexer
+ya los reporta en `errors`.
+
+La traza no cambia nada del análisis: sin `trace`, el parser no la construye; con ella, el AST y sus `id` son los mismos; el
+mismo código produce siempre la misma traza, y los eventos se pueden mandar desde un Web Worker (en el sandbox, con la
+opción `parseTrace` de `cargar`).
+
 ## 3. Compilador (`src/runtime/compiler.ts`)
 
 `compile(program)` traduce el AST a una lista de instrucciones para una máquina de pila. Por ejemplo, `x += 1` se convierte en:
@@ -171,4 +216,4 @@ cualquier otra vista.
 
 1. `bun run repl` y escribe programas pequeños.
 2. Lee los tests de `tests/` en el orden del pipeline: `lexer`, `parser`, `machine`, `stepping`.
-3. Usa `tokenize`, `parse` y `run(código, { trace: true })` para ver cada etapa del mismo programa.
+3. Usa `tokenize`, `traceParse` y `run(código, { trace: true })` para ver cada etapa del mismo programa.

package/docs/especificacion-v1.md

@@ -1,7 +1,7 @@
 # Codexivo v1 — Especificación del lenguaje
 
-> **Estado:** aprobada. Se implementa por pasos (§16). Lo que ya funciona está en
-> [`lenguaje.md`](./lenguaje.md), y todos sus ejemplos se prueban automáticamente.
+> **Estado:** implementada en la versión 1.0.0 (§16). Lo que funciona está en [`lenguaje.md`](./lenguaje.md), y todos sus
+> ejemplos se prueban automáticamente.
 >
 > Las secciones marcadas con **✅ Decidido** fueron decisiones abiertas que ya se resolvieron.
 
@@ -429,24 +429,26 @@ calculadora.suma(1, 3); // 4
 
 ## 7. Errores
 
-Cada error es un objeto, no solo un texto:
+Cada error es un objeto, no solo un texto. Los campos de la API van en inglés, como el resto (`kind`, `span`); todo lo que
+lee quien aprende va en español:
 
 ```ts
 {
-  tipo: "léxico" | "sintaxis" | "ejecución" | "límite",
-  código: "DIVISIÓN_ENTRE_CERO",
-  mensaje: "No se puede dividir entre cero.",
-  pista: "Revisa que `divisor` no valga 0 antes de dividir.",
-  inicio: { línea: 4, columna: 12 },
-  fin: { línea: 4, columna: 23 },
-  pila: ["programa", "promedio(lista)"]
+  kind: "léxico" | "sintaxis" | "ejecución" | "límite",
+  code: "DIVISIÓN_ENTRE_CERO",
+  message: "No se puede dividir entre cero.",
+  hint: "Revisa que `divisor` no valga 0 antes de dividir.",
+  span: { start: { line: 4, column: 12, offset: 80 }, end: { line: 4, column: 23, offset: 91 } },
+  callStack: ["programa", "promedio"]
 }
 ```
 
+Cada `code` tiene una explicación larga en el catálogo (`catalog.errors`).
+
 - Los mensajes dicen **qué pasó** y la pista **qué revisar**, en español correcto y con acentos.
 - El parser se recupera y reporta varios errores, pero el sandbox destaca el primero.
-- `afirmar(condición, mensaje)` detiene el programa si la condición es falsa. Es la herramienta más
-  directa para practicar verificación.
+- `afirmar(condición, mensaje)` detiene el programa con `AFIRMACIÓN_FALLIDA` si la condición es falsa; el mensaje
+  es opcional. Es la herramienta más directa para practicar verificación.
 - Sin `intentar`/`capturar` en v1: un error detiene el programa, y eso es lo que queremos que se vea.
 
 ## 8. Biblioteca estándar
@@ -655,13 +657,16 @@ estáticos y `según`/`caso`. Se pueden reconsiderar después, siempre con el pr
 
 Codexivo no tiene usuarios todavía, así que v1 se permite romper compatibilidad:
 
-- condiciones estrictas (si se aprueba §4.5);
+- condiciones estrictas (§4.5);
 - error al llamar con un número distinto de argumentos;
 - error al redeclarar o al asignar sin declarar;
 - `agregar` pasa a modificar la lista (antes regresaba una nueva);
 - un procedimiento sin `regresa` regresa `nulo` (antes regresaba el valor de su última expresión);
 - `1 / 0` pasa a ser error;
-- `ARREGLO` pasa a llamarse `lista` en mensajes y en `tipo()`.
+- `ARREGLO` pasa a llamarse `lista` en mensajes y en `tipo()`;
+- palabras reservadas nuevas (§2.5): `constante`, `dominio`, `repetir`, `veces`, `desde`, `hasta`, `con_paso`,
+  `para_cada`, `en`, `romper`, `continuar`, `mod`, `div` y las comparaciones en palabras ya no sirven como nombres;
+- sin `;`, el salto de línea termina la expresión (§2.4): una expresión partida antes de un operador es un error.
 
 ## 15. Decisiones
 

package/docs/integracion.md

@@ -62,6 +62,7 @@ promesa se rechaza.
 | `world`                                      | —              | Un mundo del [modo mundo](./modo-mundo.md), en JSON                                         |
 | `detail`                                     | `decisiones`   | Eventos por tanda: `nada`, `pasos` (`paso` y `robot`), `decisiones` (más `decide`) o `todo` |
 | `batchSize`                                  | 50 000         | Operaciones por tanda                                                                       |
+| `parseTrace`                                 | `false`        | `cargado` trae `parseTrace`: la [traza del parser](./arquitectura.md#traza-del-parser)      |
 
 ## Tandas
 

package/docs/lenguaje.md

@@ -381,14 +381,15 @@ Todo está disponible sin importar nada. Los nombres con acento también se acep
 
 ### Entrada, salida y tipos
 
-| Procedimiento           | Qué hace                                                                                                 |
-| ----------------------- | -------------------------------------------------------------------------------------------------------- |
-| `imprimir(a, b, …)`     | Escribe los valores separados por un espacio y termina la línea                                          |
-| `leer()`                | Siguiente línea de entrada como texto, o `nulo` si ya no hay                                             |
-| `leer_número()`         | Siguiente línea de entrada como número                                                                   |
-| `tipo(x)`               | `"número"`, `"texto"`, `"lógico"`, `"nulo"`, `"lista"`, `"diccionario"`, `"dominio"` o `"procedimiento"` |
-| `texto(x)`, `número(x)` | Conversiones explícitas                                                                                  |
-| `longitud(x)`           | Caracteres de un texto, elementos de una lista o claves de un diccionario                                |
+| Procedimiento                  | Qué hace                                                                                                 |
+| ------------------------------ | -------------------------------------------------------------------------------------------------------- |
+| `imprimir(a, b, …)`            | Escribe los valores separados por un espacio y termina la línea                                          |
+| `leer()`                       | Siguiente línea de entrada como texto, o `nulo` si ya no hay                                             |
+| `leer_número()`                | Siguiente línea de entrada como número                                                                   |
+| `tipo(x)`                      | `"número"`, `"texto"`, `"lógico"`, `"nulo"`, `"lista"`, `"diccionario"`, `"dominio"` o `"procedimiento"` |
+| `texto(x)`, `número(x)`        | Conversiones explícitas                                                                                  |
+| `longitud(x)`                  | Caracteres de un texto, elementos de una lista o claves de un diccionario                                |
+| `afirmar(condición, mensaje?)` | Detiene el programa si la condición es falsa (ver [Errores](#errores))                                   |
 
 ### Matemáticas
 
@@ -493,6 +494,19 @@ Error de ejecución en la línea 2, columna 5: No se puede dividir entre cero.
 Pista: Revisa que el divisor no valga 0 antes de dividir.
 ```
 
+Con `afirmar` se escribe lo que se espera que sea cierto. Si no lo es, el programa se detiene en esa línea, antes de que el
+error llegue más lejos:
+
+```codexivo
+variable precio = 120
+variable descuento = 20
+variable total = precio - descuento
+afirmar(total es_menor_que precio, "el descuento tenía que bajar el precio")
+imprimir("Total:", total)
+```
+
+Un error detiene el programa: no hay forma de atraparlo y seguir, porque lo que se busca es verlo.
+
 ## Puente hacia otros lenguajes
 
 Muchos lenguajes (C, Java, JavaScript) cuentan con un `for` de tres partes. Codexivo también lo tiene, para practicar antes de

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codexivo",
-  "version": "0.2.3",
+  "version": "1.0.1",
   "description": "Lenguaje de programación en español para practicar lógica y algoritmos, que se ejecuta en el navegador.",
   "type": "module",
   "main": "dist/index.js",

package/src/catalog.ts

@@ -227,6 +227,7 @@ const library: ProcedureEntry[] = [
 const CATEGORIES: ProcedureCategory[] = [
   'entrada y salida',
   'tipos',
+  'verificación',
   'matemáticas',
   'texto',
   'listas',

package/src/error-codes.ts

@@ -186,6 +186,11 @@ export const ERROR_CODES: Readonly<Record<string, { kind: ErrorKind; explanation
   },
 
   // ejecución
+  AFIRMACIÓN_FALLIDA: {
+    kind: 'ejecución',
+    explanation:
+      'Una llamada a `afirmar(condición, mensaje)` encontró que su condición era falsa. Afirmar es escribir lo que esperas que sea cierto en ese punto del programa; si no lo es, el programa se detiene ahí, antes de que el error llegue más lejos. Revisa los valores de las variables justo antes de esa línea.',
+  },
   CANTIDAD_DE_ARGUMENTOS: {
     kind: 'ejecución',
     explanation:

package/src/index.ts

@@ -6,8 +6,8 @@ export type { ErrorInfo, ErrorKind } from './errors';
 
 export { tokenize } from './syntax/lexer';
 export type { LexResult } from './syntax/lexer';
-export { parse } from './syntax/parser';
-export type { ParseResult } from './syntax/parser';
+export { parse, traceParse } from './syntax/parser';
+export type { ParseResult, ParseOptions, ParseEvent, PrecedenceOperator } from './syntax/parser';
 export { TokenType, KEYWORDS, isKeyword } from './syntax/token';
 export type { Token, Span, Position } from './syntax/token';
 export { childrenOf, walk } from './syntax/ast';

package/src/runtime/builtins.ts

@@ -358,6 +358,50 @@ const library: NativeValue[] = [
     },
   ),
 
+  // verificación
+  define(
+    'afirmar',
+    [1, 2],
+    {
+      level: 'principiante',
+      category: 'verificación',
+      params: [
+        { name: 'condición', type: 'lógico' },
+        { name: 'mensaje', type: 'texto', optional: true },
+      ],
+      returns: 'nulo',
+      description:
+        'Detiene el programa con un error si la condición es falsa. Sirve para escribir lo que esperas que sea cierto y comprobarlo.',
+      examples: [
+        { code: 'variable total = 2 + 2\nafirmar(total es_igual_a 4, "la suma está mal")\ntotal', result: '4' },
+      ],
+    },
+    (args, context) => {
+      const condition = args[0]!;
+      if (typeof condition !== 'boolean') {
+        throw context.fail(
+          'TIPO_DE_ARGUMENTO',
+          `\`afirmar\` espera una condición \`verdadero\` o \`falso\`, pero recibió ${describeType(typeOf(condition))} (${repr(condition)}).`,
+          '¿Quisiste comparar? Por ejemplo: `afirmar(x es_mayor_que 0)`.',
+        );
+      }
+      const message = args[1];
+      if (message !== undefined && typeof message !== 'string') {
+        throw context.fail(
+          'TIPO_DE_ARGUMENTO',
+          `El mensaje de \`afirmar\` tiene que ser un texto, pero es ${describeType(typeOf(message))}.`,
+          'Escribe el mensaje entre comillas: `afirmar(x es_mayor_que 0, "x tenía que ser positivo")`.',
+        );
+      }
+      if (condition) return null;
+      throw context.fail(
+        'AFIRMACIÓN_FALLIDA',
+        message ? `La afirmación no se cumplió: ${message}` : 'La afirmación no se cumplió.',
+        'Lo que afirmaste que era cierto no lo es en este punto. Revisa los valores de las variables justo antes de esta línea.',
+      );
+    },
+  ),
+
   // matemáticas
   define(
     'absoluto',

package/src/runtime/values.ts

@@ -68,6 +68,7 @@ export type ProcedureLevel = 'principiante' | 'intermedio' | 'avanzado';
 export type ProcedureCategory =
   | 'entrada y salida'
   | 'tipos'
+  | 'verificación'
   | 'matemáticas'
   | 'texto'
   | 'listas'

package/src/sandbox-host.ts

@@ -5,6 +5,7 @@ import { Machine, serialize } from './runtime/machine';
 import type { MachineEvent, MachineOptions, MachineStatus, SerializedValue, Snapshot } from './runtime/machine';
 import { compile } from './runtime/compiler';
 import { parse } from './syntax/parser';
+import type { ParseEvent } from './syntax/parser';
 import type * as ast from './syntax/ast';
 import type { Token } from './syntax/token';
 import { createWorld } from './world';
@@ -39,6 +40,8 @@ export interface SandboxOptions {
   detail?: EventDetail;
   /** Operaciones por tanda antes de ceder el control. Por defecto 50 000. */
   batchSize?: number;
+  /** Si `cargado` trae `parseTrace`: cómo construyó el parser el árbol, paso a paso. Por defecto `false`. */
+  parseTrace?: boolean;
 }
 
 export type SandboxRequest =
@@ -67,6 +70,8 @@ export interface Loaded {
   errors: ErrorInfo[];
   /** Semilla de `aleatorio` de esta carga. */
   seed: number;
+  /** La traza del parser (ver `parse(código, { trace: true })`), solo con la opción `parseTrace`. */
+  parseTrace?: ParseEvent[];
 }
 
 export interface Progress {
@@ -193,10 +198,18 @@ export class SandboxHost {
     this.inputClosed = false;
     this.events = [];
     this.sentOutput = 0;
-    const { program, tokens, errors } = parse(source);
+    const { program, tokens, errors, trace } = parse(source, { trace: options.parseTrace ?? false });
     this.program = errors.length === 0 ? program : undefined;
     this.machine = this.program ? this.createMachine() : undefined;
-    this.post({ type: 'cargado', id, tokens, program, errors: errors.map(error => error.toJSON()), seed: this.seed });
+    this.post({
+      type: 'cargado',
+      id,
+      tokens,
+      program,
+      errors: errors.map(error => error.toJSON()),
+      seed: this.seed,
+      ...(trace ? { parseTrace: trace } : {}),
+    });
   }
 
   private createMachine(): Machine {