codexivo 1.0.0 → 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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codexivo",
-  "version": "1.0.0",
+  "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/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/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 {